Documentation Index
Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt
Use this file to discover all available pages before exploring further.
Maleku System ships three Docker Compose files: docker-compose.yml for full local development, docker-compose.staging.yml for pre-production validation, and docker-compose.test.yml for isolated test infrastructure. All containers share a dedicated bridge network (costarica_network) so services resolve each other by name. Prometheus and Grafana are included in the default compose file but gated behind the monitoring profile so they don’t start by default.
This project uses Docker Compose V2 (docker compose with a space), not the legacy V1 docker-compose binary. If you are on an older Docker installation, upgrade to Docker Desktop 4.x or later, or install the docker-compose-plugin package.
Services
The following services are defined in docker-compose.yml:
| Service | Image | Port(s) | Purpose |
|---|
postgres | postgres:16-alpine | 5434:5432 | Primary PostgreSQL database (costaricatravel DB) |
redis | redis:7-alpine | 6381:6379 | Cache and rate-limiter state store (password-protected) |
mailhog | mailhog/mailhog:latest | 1025:1025, 8025:8025 | SMTP capture for development email testing |
backend | ./backend/Dockerfile.dev | 8000:8000 | FastAPI application with hot-reload via volume mount |
frontend | ./frontend/Dockerfile.dev | 3000:3000 | Nuxt.js 3 dev server with hot-reload via volume mount |
backup | postgres:16-alpine | — | On-demand DB backup utility (activated via --profile backup) |
prometheus | prom/prometheus:latest | 9090:9090 | Metrics collection (activated via --profile monitoring) |
grafana | grafana/grafana:latest | 3002:3000 | Dashboard visualisation (activated via --profile monitoring) |
postgres and redis require secrets via environment variables — POSTGRES_PASSWORD and REDIS_PASSWORD must be set in your shell or in a .env file at the project root before starting the stack.
Local Development
Start the full stack (backend, frontend, database, Redis, MailHog):
# Build images and start all services in detached mode
docker compose up -d
# Follow logs for a specific service
docker compose logs -f backend
# Apply Alembic migrations after first start
docker compose exec backend alembic upgrade head
# Stop and remove containers (volumes are preserved)
docker compose down
If you already have database tables from a previous run and Alembic reports a conflict, stamp the current state as the baseline without running migrations:docker compose exec backend alembic stamp head
docker compose --profile monitoring up -d
admin / value of GRAFANA_PASSWORD env var, default admin).
Hybrid Mode
For the fastest hot-reload experience during active development, run only MailHog inside Docker and start PostgreSQL, Redis, the backend, and the frontend natively:
# 1. Start MailHog in Docker
docker run -d \
--name costarica_mailhog \
-p 1025:1025 \
-p 8025:8025 \
mailhog/mailhog:latest
# 2. Start the FastAPI backend (from project root)
cd backend && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 3. Start the Nuxt.js frontend (in a separate terminal)
cd frontend && npm run dev
backend/.env points SMTP_HOST=localhost and USE_SMTP_IN_DEV=True so the backend routes email through the MailHog container. The MailHog web UI is available at http://localhost:8025.
Staging Environment
docker-compose.staging.yml mirrors production as closely as possible. It uses the production Dockerfiles (without volume mounts), runs the backend with uvicorn --workers 2 --proxy-headers, and targets a separate costaricatravel_staging database. Migrations are run automatically on container start via the entrypoint command.
Key differences from the dev compose file:
| Detail | Dev | Staging |
|---|
| Backend Dockerfile | Dockerfile.dev | Dockerfile |
| Frontend Dockerfile | Dockerfile.dev | Dockerfile |
| DB name | costaricatravel | costaricatravel_staging |
| Backend port | 8000 | 8001 |
| Frontend port | 3000 | 3001 |
| MailHog SMTP port | 1025 | 1026 |
| MailHog UI port | 8025 | 8026 |
| Workers | 1 (reload) | 2 |
docker compose -f docker-compose.staging.yml up -d --build
Makefile Commands
The project Makefile provides shortcuts for every common workflow. Run make <target> from the project root:
Development
| Target | Command |
|---|
make start | Run start.sh (interactive startup helper) |
make dev | Start backend and frontend natively (hot-reload) |
make dev-backend | uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 |
make dev-frontend | npm run dev inside frontend/ |
make dev-docker | docker compose up --build |
make stop | Kill background uvicorn and Nuxt processes |
Build
| Target | Command |
|---|
make build | Build both backend Docker image and frontend static output |
make build-backend | docker build -t costarica-backend ./backend |
make build-frontend | npm run build inside frontend/ |
Docker
| Target | Command |
|---|
make docker-up | docker compose up -d --build |
make docker-down | docker compose down |
make docker-logs | docker compose logs -f |
make docker-staging | docker compose -f docker-compose.staging.yml up -d --build |
Testing
| Target | Command |
|---|
make test | Start test infra → run all tests → tear down infra |
make test-backend | pytest -v --tb=short -x inside backend/ |
make test-backend-coverage | pytest with --cov report |
make test-frontend | npx vitest run inside frontend/ |
make test-e2e | npx playwright test |
make test-reservation | Smoke test: full reservation flow via live API |
Database
| Target | Command |
|---|
make migrate | alembic upgrade head |
make migration message="..." | Auto-generate a new migration revision |
make migration-create message="..." | Create an empty migration revision |
Code Quality
| Target | Command |
|---|
make lint | Run ruff + ESLint across the full codebase |
make lint-backend-fix | Auto-fix ruff violations in backend/ |
make security | bandit on backend + npm audit on frontend |
make pre-commit-run | Run all pre-commit hooks |
Backup
| Target | Command |
|---|
make backup | Run scripts/backup-db.sh |
make backup-local | Backup to ./backups/ |
Housekeeping
| Target | Command |
|---|
make clean | Remove __pycache__, .pytest_cache, .ruff_cache, frontend/.output, frontend/node_modules, backend/venv |
