Self-Hosting Guide

FeedElity is designed to be self-hosted. This guide covers deployment with Docker Compose, environment configuration, database persistence, backup, updates, and running without Docker.

Prerequisites

A server running Linux (or any OS with Docker support)
Docker Engine 20.10 or later
Docker Compose v2 or later (included with Docker Desktop and modern Docker Engine)
At least 512 MB RAM and 1 GB of disk space for the application and its database

Docker Deployment

The Compose stack runs two services, both built from source:

web — nginx serving the built Solid app, published on port 31000.
server — the Hono API server, published on port 31001.

Step-by-Step

git clone https://github.com/DimitriGilbert/FeedElity.git
cd FeedElity
cp docker/.env.example .env

Edit .env at the repo root and set the three FEEDELITY_* variables (see the Environment Variables section below). Generate a secure secret with:

openssl rand -base64 48

Then build and start:

docker compose up -d --build

There are no pre-built images to pull — the containers are always built from your checkout. The app will be available at http://localhost:31000.

Data Persistence

The server stores its libSQL database file at /data/local.db inside the container, persisted through a Docker volume named feedelity-data. This volume persists across container restarts and rebuilds.

On first start, the server seeds the database from your local dev snapshot (./local.db at the repo root, bind-mounted read-only). Every subsequent start reuses the existing database untouched, so your data survives restarts. If no snapshot exists, the server starts with an empty database. To inspect the volume (the Compose project is named feedelity):

docker volume inspect feedelity_feedelity-data

Platform Deployment (Dokploy / Coolify)

FeedElity can be deployed through PaaS platforms that support Docker Compose projects, such as Dokploy or Coolify.

Connect your repository. Point the platform to your FeedElity fork or clone.
Set the compose file. The platform should detect docker-compose.yml at the repository root.
Configure environment variables. Add all three FEEDELITY_* variables from the Environment Variables section below, with FEEDELITY_PUBLIC_URL and FEEDELITY_CORS_ORIGIN set to your domain.
Allow time for the build. Images are built from source, so the first deployment includes a full build of the web app and server.
Set up TLS. Most platforms handle TLS termination automatically. Configure your domain and enable HTTPS.
Deploy. The web service exposes port 31000 and the server port 31001.

Environment Variables

Copy docker/.env.example to .env at the repo root. Compose reads exactly three variables from this file and injects them into the server container:

Variable	Description	Required
FEEDELITY_AUTH_SECRET	Random string of at least 32 characters used to sign auth tokens and cookies. Generate with `openssl rand -base64 48`. Keep it stable: changing it logs everyone out and invalidates sessions. The server fails to start without it.	Yes
FEEDELITY_PUBLIC_URL	The full public URL browsers use to reach the web app, including scheme and port (for example `http://localhost:31000`). better-auth uses this as its base URL and for cookie and CORS decisions.	Yes
FEEDELITY_CORS_ORIGIN	Comma-separated list of origins allowed to call the API (CORS and better-auth trusted origins). Always include the web app origin.	Yes

Two more variables are fixed inside the server container and do not need to be configured: PORT=31001 (the port the Hono server binds to) and DATABASE_URL=file:/data/local.db (the libSQL database file in the persistent volume).

Database

The stack ships with a file-backed libSQL database: the server reads and writes /data/local.db inside the container, persisted through the feedelity-data Docker volume. There is no separate database service to run or monitor. On first start the database is seeded from the ./local.db dev snapshot in your checkout (if present); afterwards the volume copy is the single source of truth.

Updating

There are no pre-built images to pull — images are built locally from your checkout. To update, pull the latest code and rebuild:

git pull
docker compose up -d --build

The containers do not apply database migrations automatically. If a release includes schema changes, run Drizzle Kit from a checkout with DATABASE_URL set (Drizzle Kit reads it from apps/server/.env):

bun run db:migrate

Backup

Back up the Docker volume that holds the database file (local.db):

docker run --rm -v feedelity_feedelity-data:/data -v $(pwd):/backup alpine tar czf /backup/feedelity-db-backup-$(date +%Y%m%d).tar.gz -C /data .

To restore from a backup:

docker run --rm -v feedelity_feedelity-data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/feedelity-db-backup-YYYYMMDD.tar.gz"

Stop the stack before restoring so the server is not writing to the database file while you replace it.

Running Without Docker

For a single-machine setup without Docker, the repository ships a start/stop manager:

bun run serve
# or: bun run feedelity

This builds the workspace, then serves the web client on port 42666 and the API server on port 42667 (both configurable via --client-port and --server-port). The same script stops a running instance when invoked again, and the client proxies API requests to the server.

Architecture Overview

The Docker Compose setup runs two services:

web — Nginx serving the static Solid frontend. Proxies /rpc/, /api/, and /api-reference/ requests to the server service.
server — Bun runtime hosting the Hono API server with oRPC procedures and better-auth, backed by the libSQL file in the persistent volume.

Nginx handles static asset caching with 1-year expiry, gzip compression, and security headers (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy).