Docker Setup
MagicSync runs as a single Nuxt container plus a libSQL database. There is no separate backend service — chat, agents, the content board, RAG, and media tooling all run inside the site container. A small Python sidecar is available optionally for Python-only tools.
Prerequisites
- Docker (Engine 24+) with the Compose plugin (
docker compose) opensslto generate secrets
Self-Hosting (Pre-built Image)
The fastest way to run MagicSync on your own server.
Create a directory for MagicSync
bashmkdir magicsync && cd magicsyncCreate
docker-compose.ymlyamlservices: site: image: ghcr.io/leamsigc/magicsync:latest restart: unless-stopped depends_on: - db env_file: - .env environment: - NUXT_HOST=0.0.0.0 # Apply pending migrations on first boot (image ships them; see Dockerfile). - DB_MIGRATE_ON_BOOT=1 ports: - "3000:3000" db: image: ghcr.io/tursodatabase/libsql-server:latest restart: unless-stopped platform: linux/amd64 env_file: - .env environment: - JWT=${JWT} - SQLD_AUTH_JWT_KEY=${SQLD_AUTH_JWT_KEY} volumes: - ./sqld:/var/lib/sqld ports: - "8080:8080"Create a
.envfilebash# libSQL database (JWT and NUXT_TURSO_AUTH_TOKEN must match) JWT=$(openssl rand -hex 32) SQLD_AUTH_JWT_KEY=$(openssl rand -hex 32) NUXT_TURSO_DATABASE_URL=http://db:8080 NUXT_TURSO_AUTH_TOKEN=$JWT # Better Auth NUXT_BETTER_AUTH_URL=https://your-domain.com NUXT_BETTER_AUTH_SECRET=$(openssl rand -hex 32) BETTER_AUTH_SECRET=$NUXT_BETTER_AUTH_SECRET NUXT_SESSION_PASSWORD=$(openssl rand -hex 32) # Credential envelopes + machine routes NUXT_PUBLISH_SECRET=$(openssl rand -hex 32) MACHINE_BRIDGE_SECRET=$(openssl rand -hex 32) # Optional: deployment-wide provider / tool fallbacks # OPENAI_API_KEY=... # SGAI_API_KEY=... # ScrapeGraphAI default scraper # PYTHON_TOOLS_TOKEN=... # only if you run the python-tools sidecarStart MagicSync
bashdocker compose up -dAccess the application
- Open
http://localhost:3000 - Create your first account (the first user becomes the admin)
- Open
Build From Source
The repository ships a docker-compose.yml that builds the site image locally and includes the optional Python sidecar behind a Compose profile.
git clone https://github.com/leamsigc/production-example-nuxt-monorepo.git
cd production-example-nuxt-monorepo
cp .env-example .env # then fill in the values
docker compose up -d --buildOptional Python tools sidecar (Python-only tools such as ScrapeGraphAI's Python library):
docker compose --profile tools up -d --build
# then set PYTHON_TOOLS_URL=http://python-tools:8100 in .env
# (users can also point at it from AI settings → Tool backends)What the image contains
- Nuxt server output plus the musl
@libsqlbinding. ffmpegand the pinnedyt-dlpbinary (YTDLP_PATH=/usr/local/bin/yt-dlp) for the agent'sdownload_videotool and the video-cropper'sGET /api/v1/media/video-downloadingest endpoint.- Supertonic-3 TTS ONNX assets (downloaded at build time).
- No Python runtime — the agent runs in-process with the pi SDK. (The pinned
yt-dlpis a standalone pyinstaller build, so it does not need one either.)
Reverse proxy timeout:
/api/v1/media/video-downloadresolves the source before it can stream anything, so a request stays open with no response bytes while it works. Worst case isYTDLP_TIMEOUT_MS(120s default) plus, for the few sources that publish no H.264 at all, aYTDLP_TRANSCODE_TIMEOUT_MS(300s default) ffmpeg re-encode. Coolify's Traefik defaults to a 60s read timeout, which would show up as a bare proxy 504 instead of the route's own error — raise the read timeout above the total, or lower both values.
Why videos are re-encoded: sources are requested as H.264 + AAC because some browsers (Firefox on Linux) cannot decode AV1 through WebCodecs and fail later with
The given encoding is not supported. Sources that publish no H.264 at all — some Facebook reels are AV1-only — are re-encoded to H.264/AAC server-side, which needs thelibx264andaacencoders in the image. SetYTDLP_BROWSER_SAFE=0to skip that re-encode.
Scratch folder: downloads are staged in
YTDLP_DOWNLOAD_DIR(default/tmp/magicsync-video), which is created on demand. Each download gets its own subfolder that is unlinked once the response settles, so nothing is retained, but peak use isYTDLP_MAX_MB(200MB default) per in-flight request. Mount a real volume at that path rather than relying on the container's overlay/tmp. See.env-example→ Video Ingestion.
Development
For a hot-reload dev container:
docker compose -f docker-compose.dev.yml up -dThe dev image includes bash, curl, ffmpeg, and the pinned yt-dlp binary. For the Python sidecar in dev, run it on the host with pnpm python-tools:dev and point AI settings at http://localhost:8100.
Environment Variables
| Variable | Required | Description |
|---|---|---|
JWT / NUXT_TURSO_AUTH_TOKEN | Yes | libSQL auth token pair — must be the same value |
SQLD_AUTH_JWT_KEY | Yes | libSQL server signing key |
NUXT_TURSO_DATABASE_URL | Yes | http://db:8080 in Compose (or file:./local.db for dev) |
NUXT_BETTER_AUTH_URL | Yes | Public URL of the site |
NUXT_BETTER_AUTH_SECRET / BETTER_AUTH_SECRET | Yes | Auth signing secret — must match |
NUXT_SESSION_PASSWORD | Yes | Session encryption (32+ chars) |
NUXT_PUBLISH_SECRET | Yes | AES-256-GCM key for credential envelopes and tool-backend secrets |
MACHINE_BRIDGE_SECRET | Yes | HMAC secret for GitHub Actions / internal machine routes |
OPENAI_API_KEY / NUXT_GOOGLE_GENERATIVE_AI_API_KEY | No | Server-side provider keys (users can override per business) |
SGAI_API_KEY | No | Deployment fallback ScrapeGraphAI key |
PYTHON_TOOLS_URL / PYTHON_TOOLS_TOKEN | No | Python tools sidecar (only with the tools profile) |
AGENT_DEFAULT_PROVIDER / AGENT_DEFAULT_MODEL | No | Fallback model when a user has no effective config |
DB_MIGRATE_ON_BOOT | No | 1 applies pending migrations on container boot (fail-fast). Set by docker-compose.yml; DRIZZLE_MIGRATIONS_DIR is baked into the image |
See Self-Hosting for the full variable reference, including AGENT_* limits.
Updating, Backups, Logs
# Update to the latest image
docker compose pull && docker compose up -d
# Stop / remove containers
docker compose down
# Logs
docker compose logs -f site
# Back up the database files
cp -r sqld backups/sqld-$(date +%Y%m%d)Troubleshooting
| Symptom | Fix |
|---|---|
MODEL_NOT_CONFIGURED in chat | Set a provider/model in Account → AI settings, or set AGENT_DEFAULT_PROVIDER/AGENT_DEFAULT_MODEL |
SCRAPEGRAPH_NOT_CONFIGURED | Add a ScrapeGraphAI key in AI settings → Tool backends or set SGAI_API_KEY |
PYTHON_BACKEND_UNREACHABLE | Start the sidecar (docker compose --profile tools up -d) and verify PYTHON_TOOLS_URL |
| Database connection failed | Ensure JWT equals NUXT_TURSO_AUTH_TOKEN and NUXT_TURSO_DATABASE_URL is http://db:8080 |
| Cannot log in | Check NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, and NUXT_SESSION_PASSWORD |
| Container unhealthy | Check docker compose logs site; first boot runs migrations and can take a moment |
More Deployment Options
- Self-Hosting — full env reference and upgrades
- Coolify Deploy — deploy with the pre-built image
ghcr.io/leamsigc/magicsync - Tool Backends — ScrapeGraphAI and the Python tools sidecar