Self Hosting Lilypad

Lilypad is fully open-source and can be self-hosted in your own infrastructure.

You can also run Lilypad on your local machine.

Requirements:

To self-host Lilypad, you’ll need:

1. Python 3.10+
2. PostgreSQL
3. A GitHub or Google account (for authentication)
4. Docker

Setup

First, you’ll need to clone the repository:

git clone [email protected]:Mirascope/lilypad.git
cd lilypad

Next, you’ll need to install uv and the libraries dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync --all-extras

Going forward, replace http://localhost:8000 with the URL where you’re hosting Lilypad if not there.

Authentication

First, you’ll need to generate and set JWT secret (e.g. using https://jwtsecret.com/generate).

Then set it in your environment:

LILYPAD_JWT_SECRET=...

Next, you’ll need to set up OAuth 2.0 Authentication. You can choose between GitHub or Google:

• Homepage URL: http://localhost:8000
• Authorization Callback URL: http://localhost:8000/auth/callback

GitHub

To authenticate with GitHub, create a new OAuth app on GitHub and set the following environment variables:

LILYPAD_GITHUB_CLIENT_ID=...
LILYPAD_GITHUB_CLIENT_SECRET=...

Google

To authenticate with Google, create a new OAuth app on Google and set the following environment variables:

LILYPAD_GOOGLE_CLIENT_ID=...
LILYPAD_GOOGLE_CLIENT_SECRET=...

Client

First, set your environment variables:

LILYPAD_SERVE_FRONTEND=true

You can optionally set LILYPAD_REMOTE_CLIENT_URL to the URL where you’re hosting the client separately. In this case, you would set LILYPAD_SERVE_FRONTEND=false.

Now, build the client:

cd client
touch .env
echo "VITE_REMOTE_API_URL=http://localhost:8000/v0" > .env
pnpm i
pnpm run build
cd ..

Server

First, you’ll need to build the image:

DOCKER_BUILDKIT=1 docker build -t lilypad .

Hosted

You’ll need to set up a PostgreSQL database and set the following environment variables:

# PostgreSQL
LILYPAD_DB_HOST=...
LILYPAD_DB_NAME=...
LILYPAD_DB_PASSWORD=...
LILYPAD_DB_PORT=...
LILYPAD_DB_USER=...
 
# Server
LILYPAD_REMOTE_API_URL=http://localhost:8000
LILYPAD_REMOTE_CLIENT_URL=http://localhost:8000

Run the server:

docker run -p 8000:8000 --env-file .env lilypad

You should now be able to access your Lilypad instance at http://localhost:8000.

Local

Alternatively, you can use Docker Compose to run everything together locally:

docker-compose up

You should now be able to access your Lilypad instance at http://localhost:8000.

Note that this results in a PostgreSQL database running in a container. Should you spin down the container, you’ll lose all data.

Application

In your LLM code, make sure you set the API and Client URLs to point to your self-hosted instance:

LILYPAD_REMOTE_API_URL=http://localhost:8000
LILYPAD_REMOTE_CLIENT_URL=http://localhost:8000

Now you can use Lilypad as documented.