Quick Start Guide

Choose the right stack

The evaluation file starts the API, durable worker, PostgreSQL and Redis. It has no dashboard. AI providers default to disabled; starting Ollama and downloading models are separate, optional steps.

Evaluation only: this stack uses mock authentication and known development credentials. Its API port binds to 0.0.0.0 by default. Run it only on a trusted, isolated machine with inbound access blocked. Do not expose it to a network or use student records. Use production self-hosting for real data.

1. Check prerequisites and get the release

You need Git, Docker with Compose v2, curl, OpenSSL and enough disk and memory for container builds. Model requirements depend on your selection. Initial downloads and builds can take substantially longer than a few minutes.

docker version
docker compose version
git clone --branch v0.9.11 --depth 1 https://github.com/Aelira-AI/aelira-core.git
cd aelira-core

Use a new directory. The shipped files use fixed container names, so do not run this alongside another Aelira stack using those names.

2. Keep the evaluation provider choices explicit

No .env file is required for this fresh evaluation. Set these process defaults in the same terminal to avoid inheriting an unintended provider. Authenticated workspaces have separate saved provider selections; these variables do not disable an existing workspace configuration.

export LLM_PROVIDER=none
export LLM_FALLBACK_PROVIDER=none
export EMBEDDING_PROVIDER=none

In v0.9.11, every worker job also requires a valid TOKEN_ENCRYPTION_KEY, even without integrations. Generate a private key for this evaluation:

export TOKEN_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')"

The shipped quickstart does not pass this key into containers. Add the following entry inside its shared environment: &api-environment mapping, alongside JWT_SECRET. The worker inherits that mapping. Exporting the key without this entry is insufficient.

TOKEN_ENCRYPTION_KEY: ${TOKEN_ENCRYPTION_KEY:?Set TOKEN_ENCRYPTION_KEY}

Retain the same key privately for restarts; do not commit or publish it. Only generate a replacement for a genuinely new, empty evaluation. Production keys must persist with the encrypted data they protect.

3. Start and check the services

Before starting, edit the API ports entry in docker-compose.quickstart.yml from 8000:8000 to 127.0.0.1:8000:8000. This keeps the mock-auth API on the local machine. Do not change its private container-to-container listener.

docker compose -f docker-compose.quickstart.yml config --quiet
docker compose -f docker-compose.quickstart.yml up -d --build
docker compose -f docker-compose.quickstart.yml ps
curl --fail-with-body http://localhost:8000/ready
docker compose -f docker-compose.quickstart.yml logs --tail=50 worker

The API runs database migrations on startup. Wait for both API and worker health checks to pass. API readiness checks database and Redis dependencies; it does not prove that the worker can finish jobs.

4. Open the API reference

Open http://localhost:8000/docs on the evaluation machine. The dashboard at port 5173 is a separate source-development workflow, not part of this Compose file. The production stack includes a dashboard at localhost port 8080.

5. Submit a synthetic test document

Use a non-sensitive PDF you own. This unauthenticated request is only for the isolated mock-auth evaluation above.

curl --fail-with-body --request POST http://localhost:8000/education/pdf/scan --form '[email protected]'

The response is a scan handle, not a completed score. Follow submit, poll and retrieve to get the completed result. Production requests require an API key. Read scores and review before treating any generated change as a verified fix.

Optional local AI infrastructure

Enable the Ollama profile and pull the models you intend to use. This prepares model infrastructure; it does not enable AI for a workspace.

docker compose -f docker-compose.quickstart.yml --profile ollama up -d ollama
docker compose -f docker-compose.quickstart.yml exec ollama ollama pull gemma3:4b
docker compose -f docker-compose.quickstart.yml exec ollama ollama pull qwen2.5-coder:7b
docker compose -f docker-compose.quickstart.yml exec ollama ollama pull qwen2.5vl:3b
docker compose -f docker-compose.quickstart.yml exec ollama ollama pull nomic-embed-text:latest

For authenticated document, image and web AI operations, follow workspace AI configuration in the full dashboard: an administrator saves the provider, model choices and primary/fallback selection in Settings → AI Provider Settings. Workspace text, code and vision models use saved values or provider defaults, not the corresponding process-level OLLAMA model overrides.

Embedding configuration is separate: EMBEDDING_PROVIDER and OLLAMA_EMBEDDING_MODEL control optional semantic retrieval. Check the local model guide for hardware requirements. Cloud providers and fallback routes are explicit alternatives, not a consequence of self-hosting.

Stop the evaluation and choose a next step

docker compose -f docker-compose.quickstart.yml --profile ollama stop

This stops services without removing stored data. For errors, use troubleshooting. For the full dashboard, accounts, TLS and backups, follow self-hosting. Developers can use the tagged development Compose file with the repository's source-development instructions.