Choose where to run LyEve
LyEve ships as two container images. You run each one where it fits, next to a database you provide.
| Image | What it is | Listens on |
|---|---|---|
ghcr.io/lyeve-labs/lyeve-core | The engine: the Admin API and the Content API | 3001 (Admin API), 3002 (Content API) |
ghcr.io/lyeve-labs/lyeve-admin | The admin console, a Node server that calls the engine for the browser | 3002 |
The engine is a long-running server. It keeps a pool of database connections open, holds its signing key, and applies its migrations when it starts. A platform that starts a process per request, such as Vercel Functions, Cloudflare Workers or Netlify Functions, cannot host it. Concepts explains what each API is for.
Compare the hosts
Section titled “Compare the hosts”| Host | Best for | What you give up | Guide |
|---|---|---|---|
| Docker | Trying LyEve, or one server you manage yourself | You wire the database, the proxy and TLS | Docker images |
| Docker Compose | The whole stack on one server: engine, admin console, Postgres and TLS | One machine, so no failover | Docker Compose |
| Kubernetes | Several replicas, rolling deploys and a cluster you already run | More than one replica needs Redis, an S3 bucket and a shared signing key | Kubernetes |
| Google Cloud Run | An engine that scales to zero and bills per request | One API per service, cold starts, and a new signing key per instance | Cloud Run |
| Fly.io | Both APIs public from one small Machine | Usage is billed, the Admin API answers on port 8443, and each Machine start signs everyone out unless a volume keeps the signing key | Fly.io |
| Railway | Both APIs from one service, with a volume for the signing key | No lasting free plan, usage is billed | Railway |
| Render | A free engine for a demo or staging | One API per service, and a free service spins down and signs everyone out | Render |
| Free-tier stack | An engine and a database at $0 a month | Cold starts, tight connection limits, and no free host for the admin console | Free-tier stack |
| Stateless mode | A webhook relay in one container, with no database | No admin console, one tenant, and nothing kept across a restart | Stateless mode |
Supported databases
Section titled “Supported databases”The engine stores everything in one database. It reads the type from the scheme of
DATABASE_URL and creates its tables on first start.
| Database | DATABASE_URL form |
|---|---|
| PostgreSQL | postgres://user:pass@host:5432/lyeve?sslmode=require (or postgresql://) |
| MySQL 8 or later | mysql://user:pass@tcp(host:3306)/lyeve, with the host in tcp(...) |
| SQL Server 2019 or later, and Azure SQL | sqlserver://user:pass@host:1433?database=lyeve |
SQL Server needs read committed snapshot isolation turned on before it takes traffic. See Installation.
Use a dedicated database user. A production engine refuses to start as postgres on
PostgreSQL, root on MySQL or sa on SQL Server.
SQLite, Turso and libSQL are not supported
Section titled “SQLite, Turso and libSQL are not supported”The engine reads any URL whose scheme is not one of the above as PostgreSQL. A URL for SQLite, Turso or libSQL therefore fails to connect, and the engine does not start. For a free database with no server to run, use managed Postgres instead:
Both are a DATABASE_URL value and nothing more. For an engine with no database at all, see
Stateless mode.
The admin console needs a server, not Vercel or Cloudflare Pages
Section titled “The admin console needs a server, not Vercel or Cloudflare Pages”The admin console ships only as the container image ghcr.io/lyeve-labs/lyeve-admin. Vercel
and Cloudflare Pages build a site from its source repository and do not run a container image,
and the console's source is not published. The console cannot be hosted on either.
Run the image on a host that runs containers. The console's server sends every /api call to
one base URL, CORE_INTERNAL_URL, so that URL must route /api/admin to the engine's port
3001 and every other /api path to port 3002. A small proxy or an Ingress does that:
- Docker Compose: the engine, the console, Postgres and a TLS proxy on one host.
- Kubernetes: the same images on a cluster, routed by an Ingress.
The single-container engine hosts above give the engine no such route, so the free-tier stack has no host for the console. Run it with Compose on a server you control.
Before go-live
Section titled “Before go-live”- Production checklist: every setting to confirm, one line each.
- Configuration: every variable and its default.
- Scaling: more than one replica, Redis and load shedding.