Installation

Nexora runs as a Docker Compose stack. Prerequisites: Docker 24+ and Docker Compose v2.

Clone the repository


git clone https://gitlab.com/parendum/nexora/nexora.git
cd nexora

Configure environment


cp .env.example .env

Edit .env with required values — see Configuration for all variables.

Minimum required:


SECRET_KEY=your-secret-key-at-least-32-characters-long
ENCRYPTION_KEY=your-fernet-key-44-chars-base64
POSTGRES_PASSWORD=strongpassword
REDIS_PASSWORD=strongpassword

Generate a Fernet key:


python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Start services

Production


make up

Starts all services in production mode. Default port: 80.

Run database migrations


docker compose exec backend alembic upgrade head

Access Nexora

Open http://localhost (prod) or http://localhost:8080 (dev).

What gets deployed

Service	Port	Description
`nginx`	80 / 8080	Reverse proxy — routes `/api` to backend, `/` to frontend
`backend`	8000 (internal)	FastAPI — REST API + WebSocket
`frontend`	3000 (internal)	Next.js UI
`postgres`	5432 (internal)	PostgreSQL 16
`redis`	6379 (internal)	Redis 7 — pub/sub + cache

Make targets


make up        # start production stack
make dev       # start with hot-reload
make down      # stop all services
make logs      # tail all logs
make ps        # show running containers
make clean     # stop + remove volumes (DESTRUCTIVE — deletes DB data)

make clean destroys all Docker volumes including the database. Only use it for a full reset.

Troubleshooting

Backend fails to start with “weak secret” error

Production mode validates SECRET_KEY length (≥32 chars). Use a strong random value.

Port 80 already in use

Set HTTP_PORT=8080 in .env.

Migrations fail

Ensure the backend container is running: make ps. Then re-run:


docker compose exec backend alembic upgrade head