Self-Hosting Guide

Before you deploy

Use Docker with Compose v2 and capacity for PostgreSQL, Redis, the API, workers, uploads and backups. Model memory and storage depend on the models selected. Measure representative workloads before sizing a production service; the local AI guide describes model requirements.

For a disposable API-only trial, use Quick Start. Never promote its known credentials or mock authentication into production. Read the release-pinned deployment guide alongside this summary.

1. Get the release and configure it

git clone --branch v0.9.11 --depth 1 https://github.com/Aelira-AI/aelira-core.git
cd aelira-core
cp .env.example .env

Edit .env privately. Replace every placeholder in its required production section, including POSTGRES_PASSWORD, JWT_SECRET and SESSION_REPLAY_ENCRYPTION_KEY. Use distinct random values; the session replay key must be a valid Fernet key and must persist across restarts and replicas. Follow the generation instructions in .env.example.

Set AELIRA_VERSION to 0.9.11. Configure PUBLIC_API_URL, PUBLIC_DASHBOARD_URL and CORS_ORIGINS for your actual HTTPS origins. Leave the direct-host DATABASE_URL and REDIS_URL examples commented when using the bundled database and Redis. Production Compose supplies their container addresses.

Keep ENV=production, mock authentication disabled and public signup closed. Configure SMTP before provisioning accounts. TOKEN_ENCRYPTION_KEY is required for all worker jobs in v0.9.11, even without integrations; replace its placeholder with a valid, persistent Fernet key in .env. Both production API and worker load that file. Do not treat it as optional because the template groups it with integration settings. Set a separate BYOK_ENCRYPTION_KEY before enabling stored workspace AI credentials.

2. Choose providers deliberately

# In .env: disable process-default provider selection
LLM_PROVIDER=none
LLM_FALLBACK_PROVIDER=none
EMBEDDING_PROVIDER=none

These environment settings do not disable providers already selected in a workspace. For local AI infrastructure, enable the ollama Compose profile and explicitly pull the models. OLLAMA_HOST sets the server address. Embedding selection is separate; OLLAMA_EMBEDDING_MODEL selects its model. See the local AI infrastructure example.

Cloud providers require an explicit choice and credentials. Self-hosting alone does not mean documents stay local. Check fallback routes, outbound traffic, logs, storage, backups and administrator access. LMS AI processing has an additional authorization and provider-readiness policy; provider credentials alone do not authorize course-content processing.

Workspace AI configuration

After provisioning an administrator, open Settings → AI Provider Settings in the dashboard. Configure the provider and text, code and vision models, test the configuration, and explicitly select the primary provider and optional fallback. A new workspace has no selected provider. For cloud providers, save the workspace credential through this administrator workflow after configuring BYOK_ENCRYPTION_KEY.

Authenticated document, image and web operations resolve the saved workspace provider rows. Workspace model values, or provider defaults when unset, take precedence over process-level model settings. Setting LLM_PROVIDER in .env and restarting containers does not configure that workspace. To disable workspace AI, clear its provider selection through the administrator settings.

The workspace provider API exposes configuration, testing and selection for authorized administrators. Its updates require the current configuration revision; do not reuse a stale revision or place credentials in URLs. LMS content also needs its separate AI authorization policy.

3. Understand the network boundary

The production file binds the API to 127.0.0.1:8000 and the dashboard to 127.0.0.1:8080 by default. PostgreSQL, Redis and optional Ollama remain on the Compose network. The worker uses the same API image, database, provider configuration and shared upload volume.

The published dashboard uses same-origin /api requests. Its nginx configuration forwards /api/ to the API service and removes that prefix. Direct API clients use /education routes; dashboard-proxied requests therefore use /api/education routes. There is no /api/v1 alias.

4. Configure TLS and access

Compose does not include TLS termination or automatic certificate setup. Configure your existing reverse proxy to serve the dashboard and API over HTTPS, using the origins you set above. Keep database, Redis and model ports private. Configure only the actual proxy network in TRUSTED_PROXY_CIDRS; do not trust arbitrary forwarded headers.

Restrict initial access while bootstrapping: the first verified magic-link login on an empty database becomes the administrator. Configure and test SMTP, claim that account, and invite other staff through administration. Do not leave an unclaimed installation open to the public. The account provisioning section covers department invitations and SSO/LTI provisioning.

5. Start the matched stack and verify readiness

docker compose -f docker-compose.prod.yml config --quiet
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps
curl --fail-with-body http://localhost:8000/live
curl --fail-with-body http://localhost:8000/ready
docker compose -f docker-compose.prod.yml exec worker python -m src.jobs.healthcheck --mode readiness --json

The API entrypoint runs migrations and stops on failure. A responsive API is not a working queue: verify a fresh worker readiness result, then submit a synthetic document and follow it to completion. Check login, review and download from the dashboard before admitting real content. A local dashboard health response alone does not prove that journey.

With local AI selected, add --profile ollama to startup and pull your chosen models before testing AI features. Do not enable a paid provider as an implicit fallback.

Capacity and configuration

JOB_WORKER_MAX_CONCURRENCY controls jobs per worker; the shipped default is one. JOB_WORKER_CPUS and JOB_WORKER_MEMORY_LIMIT bound resource use. Increase limits only after measuring peak usage and API responsiveness. Keep JOB_WORKER_STOP_GRACE_PERIOD longer than JOB_WORKER_MAX_EXECUTION_SECONDS so shutdown can drain work.

Upload limits are format-specific settings in settings.py. Reverse-proxy request limits also apply. Avoid changing only one layer and assuming the end-to-end limit changed.

Backups, upgrades and recovery

Back up PostgreSQL and the shared /app/uploads volume, including REMEDIATION_ARTIFACT_DIR and report artifacts. Retain configuration and encryption keys securely, separately from database dumps. Test a restore into an isolated environment and confirm original files and saved artifacts can be opened; a database dump alone does not preserve file bytes.

1. Read the target release notes, pause intake and drain active work before upgrading.
2. Take verified backups and record the current image digests and configuration.
3. Pin the new release consistently for API, worker and dashboard. Run its migrations and inspect the exit status before resuming service.
4. Check API readiness, worker health, a completed synthetic scan and dashboard review/download. Reopen intake only after these pass.

Rollback may require the matching database backup as well as matching images. Do not combine an old worker with a newer API or schema. Do not manually delete artifact rows or files to bypass a failed cleanup. See the upgrade and recovery procedures and troubleshooting.