Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sdurutr436/stay-sidekick/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose is the recommended way to run the full Stay Sidekick stack locally — it starts all five services (nginx, frontend, web, backend, postgres) with a single command and wires them together on an internal Docker network called app-net. Only nginx publishes a port to the host (80:80); every other service communicates exclusively over the internal network by service name.

​
Prerequisites

Make sure the following tools are installed before continuing:
ToolMinimum version
Docker24+
Docker Composev2 (plugin — ships with Docker Desktop and recent Docker Engine releases)
GitAny recent version
1

Clone the repository

git clone https://github.com/sdurutr436/stay-sidekick.git
cd stay-sidekick
2

Prepare environment files

Stay Sidekick requires two .env files before the stack can start. Both are versioned as .env.example files — copy them and fill in the required values.Root .env — PostgreSQL credentials:
cp .env.example .env
Open .env and set a secure value for POSTGRES_PASSWORD. If you change POSTGRES_PASSWORD you must also update the password segment of DATABASE_URL to match.backend/.env — Flask API secrets:
cp backend/.env.example backend/.env
Open backend/.env and set at minimum these three variables:
VariableHow to generate
SECRET_KEYpython -c "import secrets; print(secrets.token_urlsafe(32))"
JWT_SECRET_KEYpython -c "import secrets; print(secrets.token_urlsafe(32))"
FERNET_KEYpython -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
web/.env ships with a Cloudflare Turnstile test key that is always valid in development — no changes needed there for local use.
3

Build images and start the stack

docker compose up -d --build
The first build downloads base images and compiles all four custom images (nginx, frontend, web, backend). Subsequent starts reuse the layer cache and are much faster.To watch all service logs in real time during startup, omit -d:
docker compose up --build
4

Verify all services are healthy

Check that all five containers are running:
docker compose ps
Expected output:
NAME                        IMAGE                  STATUS
stay-sidekick-nginx-1       stay-sidekick-nginx    Up X seconds
stay-sidekick-frontend-1    stay-sidekick-frontend Up X seconds
stay-sidekick-web-1         stay-sidekick-web      Up X seconds
stay-sidekick-backend-1     stay-sidekick-backend  Up X seconds
stay-sidekick-postgres-1    postgres:16-alpine     Up X seconds (healthy)
Confirm the API is reachable through nginx:
curl -s http://localhost/api/health
# {"status": "ok"}
5

Open the app and log in

Navigate to http://localhost/menu/ in your browser. Use the seed credentials created automatically on first boot:
FieldValue
Emaildev@staysidekick.es
Passwordadmin123
Roleadmin (with es_superadmin = true)
The seed credentials above exist only for local development. They are inserted automatically by backend/seed.sql on the first volume creation. Never use these credentials in a production deployment.

​
Service URLs

All traffic enters through the nginx reverse proxy on port 80. nginx routes requests to the appropriate internal service by path prefix.
URLServiceDescription
http://localhost/web11ty static public site
http://localhost/menu/frontendAngular 21 SPA (operations panel)
http://localhost/api/backendFlask REST API

​
Useful Docker commands

# Show the status of all containers
docker compose ps

# Tail logs from all services
docker compose logs -f

# Tail logs from a single service
docker compose logs -f backend

# Restart a single service without rebuilding
docker compose restart backend

# Stop all containers (data volumes are preserved)
docker compose stop

# Stop and remove containers (volumes are preserved)
docker compose down

# Stop and remove containers AND the postgres data volume
docker compose down -v

​
Troubleshooting

DATABASE_URL variable is not set The root .env file is missing. Run cp .env.example .env and set POSTGRES_PASSWORD.
502 Bad Gateway from nginx nginx cannot resolve an upstream service hostname on the internal app-net network. This usually means a service failed to start cleanly. Run docker compose ps to identify which container is not running, then inspect its logs: 
docker compose logs backend
Tables are missing / schema was not applied The PostgreSQL schema (backend/db/schema.sql) is applied only on the very first creation of the postgres_data volume. If the volume already exists from a previous run that failed mid-init, the init scripts are skipped. Reset everything with: 
docker compose down -v && docker compose up -d --build
Flask does not start: KeyError: 'SECRET_KEY' The SECRET_KEY variable is required and was not found. Verify that backend/.env exists and contains a non-empty SECRET_KEY value.
Port 80 is already in use Another process on your machine is listening on port 80. Either stop it, or change the nginx port mapping in docker-compose.yml from "80:80" to "8080:80" and access the app on http://localhost:8080/ instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us