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.

This guide walks you through running the complete Stay Sidekick stack on your local machine using Docker Compose. A single docker compose up -d --build command starts all five services — nginx, Angular frontend, 11ty static site, Flask backend, and PostgreSQL — behind a single Nginx reverse proxy on port 80. No manual service wiring required.
The seed credentials below are for local development only. Never use them in a production deployment. Generate strong, unique credentials before exposing any service to the internet.

​
Run the Full Stack Locally

1

Check Prerequisites

Make sure you have the following tools installed before proceeding:
ToolMinimum Version
Docker24+
Docker Composev2 (plugin)
Gitany
Verify your Docker installation:
docker --version
docker compose version
2

Clone the Repository

Clone the Stay Sidekick repository and enter the project directory:
git clone https://github.com/sdurutr436/stay-sidekick.git
cd stay-sidekick
3

Copy the Environment Files

The stack is configured via three .env files. Copy the provided examples to get started:
cp .env.example .env                  # PostgreSQL credentials and Turnstile site key
cp backend/.env.example backend/.env  # Flask keys, JWT, Mailgun, Discord, AI, and more
web/.env is already included in the repository with the official Cloudflare Turnstile test key (1x00000000000000000000AA), which is always valid in development. No action needed for web/.env on first run.
The root .env ships with safe development defaults. At minimum, review these values before starting:
VariableFileRequiredDescription
POSTGRES_PASSWORD.envYes (prod)Change before any production deployment
SECRET_KEYbackend/.envYesFlask secret key — minimum 32 random characters
JWT_SECRET_KEYbackend/.envYesHS256 signing key for all JWT tokens
FERNET_KEYbackend/.envYesFernet key for encrypting PMS/AI API keys at rest
4

Build Images and Start the Stack

Build all service images and start the stack in the background:
docker compose up -d --build
On first run, Docker will build four custom images (nginx, frontend, web, backend) and pull postgres:16-alpine. This may take a few minutes depending on your connection speed.To follow the logs in real time during startup:
docker compose logs -f
5

Verify Service Health

Confirm that all five containers are running and the API is responding:
docker compose ps
You should see five services with Up status. Then confirm the API health endpoint:
curl -s http://localhost/api/health
Expected response:
{"status": "ok"}
You can also check the nginx security headers are applied:
curl -I http://localhost/
# X-Frame-Options: SAMEORIGIN
# X-Content-Type-Options: nosniff
# Referrer-Policy: strict-origin-when-cross-origin
# Content-Security-Policy: default-src 'self'; ...
6

Open the App and Log In

Navigate to http://localhost/menu/ in your browser. Log in using the development seed credentials created automatically on first startup:
FieldValue
Emaildev@staysidekick.es
Passwordadmin123
Roleadmin (superadmin privileges)
After logging in you will land on the main dashboard showing the tool catalog and external integration status for the seed company.

​
Available URLs

After a successful startup, the following endpoints are available on your local machine:
URLServiceDescription
http://localhost/11ty static sitePublic landing page and legal content
http://localhost/menu/Angular 21 SPAPrivate operational panel (requires login)
http://localhost/api/Flask REST APIBackend API (JSON responses)
All three routes are served through the single nginx container on port 80. No other ports are exposed to the host.

​
Development Without Docker

For faster iteration on the frontend and static site without running the full Docker stack, use the provided development scripts. These start 11ty and Angular in parallel with hot-reload enabled. Linux / macOS: 
chmod +x dev.sh
./dev.sh
Windows: 
dev.bat
Alternative — direct pnpm invocation: 
pnpm install
pnpm run dev
This starts two development servers:
URLService
http://localhost:808011ty static site (with watch)
http://localhost:4200Angular SPA (with hot-reload)
The development servers do not include the Flask backend or PostgreSQL. To test authenticated API calls during development, run the full Docker stack and point the Angular dev server at http://localhost/api/ — or start the Flask backend directly with cd backend && python run.py.
To start individual services: 
# Static site only
pnpm run dev:web

# Angular SPA only
pnpm run dev:app

# Flask backend (requires Python 3.12+)
cd backend && python run.py

​
First-Time Volume Reset

If the database was created without the seed data (for example, if the volume already existed from a previous partial run), tear down the stack including volumes and rebuild: 
docker compose down -v && docker compose up -d --build
docker compose down -v permanently deletes the postgres_data volume and all data stored in it. Only use this command in development when you want a clean slate.

​
Useful Docker Commands

docker compose ps                  # List running containers and their status
docker compose logs -f             # Follow logs from all services
docker compose logs -f backend     # Follow logs from the Flask backend only
docker compose restart backend     # Restart a single service without rebuilding
docker compose stop                # Stop all containers (data is preserved)
docker compose down                # Stop and remove containers (volumes kept)
docker compose down -v             # Stop, remove containers AND the database volume

Build docs developers (and LLMs) love

Get started for freeTalk to us