Skip to main content

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.

This guide walks you through cloning the repository, spinning up every service with a single Docker Compose command, running database migrations, optionally seeding demo data, and making your first authenticated API request — all in under five minutes. By the end you will have a fully operational local instance of the Maleku System with the frontend, backend, PostgreSQL, Redis, and MailHog all running and connected.

​
Service URLs

Once the stack is running, these are the local addresses for every service:
ServiceURLNotes
Frontendhttp://localhost:3000Nuxt.js 3 (SSR dev server)
APIhttp://localhost:8000FastAPI backend
Swagger UIhttp://localhost:8000/docsInteractive API docs (debug mode only)
ReDochttp://localhost:8000/redocAlternative API docs (debug mode only)
MailHoghttp://localhost:8025Catches all outgoing dev emails
Metricshttp://localhost:8000/metricsPrometheus scrape endpoint

​
Steps

1

Clone the repository and copy environment files

Clone the project and create your local environment files from the provided examples. Both files must exist before Docker Compose can start the services.
git clone https://github.com/your-org/costa-rica-travel.git
cd costa-rica-travel

# Copy backend environment file and fill in required secrets
cp backend/.env.example backend/.env
Open backend/.env in your editor and set at minimum these three required values — the backend will refuse to start without them:
# Generate a strong key with:
# python3 -c 'import secrets; print(secrets.token_hex(32))'
SECRET_KEY=your-32-character-minimum-secret-key

DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/costaricatravel
POSTGRES_PASSWORD=your-postgres-password
REDIS_PASSWORD=your-redis-password
2

Start all services with Docker Compose

A single command builds the images and starts all containers in detached mode:
docker compose up -d
This brings up the following containers:
ContainerImagePurpose
costarica_backend./backend/Dockerfile.devFastAPI app on port 8000
costarica_frontend./frontend/Dockerfile.devNuxt.js dev server on port 3000
costarica_postgrespostgres:16-alpinePrimary database on port 5434
costarica_redisredis:7-alpineCache and rate limiting on port 6381
costarica_mailhogmailhog/mailhog:latestEmail capture UI on port 8025
Wait for the health checks to pass (about 20–30 seconds). You can watch progress with:
docker compose logs -f backend
3

Run database migrations

Once the costarica_postgres health check is green, apply all Alembic migrations to bring the schema up to date:
docker compose exec backend alembic upgrade head
You should see Alembic print each migration revision as it is applied. If the database schema is already at head from a previous run, use alembic stamp head to mark it without re-running migrations:
docker compose exec backend alembic stamp head
4

Seed demo data (optional)

Populate the database with Costa Rica destinations, sample vendors, properties, and tours using the built-in seed script. The script is idempotent — it is safe to run multiple times.
docker compose exec backend python -m app.scripts.seed_costa_rica
After seeding you will have demo listings browsable at http://localhost:3000 and searchable via GET /api/v1/search.
5

Make your first API request

Register a new user account, then exchange the credentials for a JWT access token.Register a user
curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "traveller@example.com",
    "password": "Secure@123",
    "full_name": "Ada Lovelace"
  }' | python3 -m json.tool
A verification email is sent to MailHog (http://localhost:8025) — no real SMTP configuration is needed in development.Log in and receive tokens
curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "traveller@example.com",
    "password": "Secure@123"
  }' | python3 -m json.tool
The response contains an access_token (valid for 60 minutes) and a refresh_token (valid for 7 days). Pass the access token as a Bearer header on all subsequent requests:
curl -s http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer <your_access_token>" | python3 -m json.tool
Hybrid development mode — if you already have PostgreSQL and Redis running natively (or in standalone Docker containers), you can skip the database services in Compose and run only MailHog for email capture, then start the backend and frontend as native processes for instant hot-reload:
# Start only MailHog
docker run -d --name costarica_mailhog \
  -p 1025:1025 -p 8025:8025 \
  mailhog/mailhog:latest

# Start backend natively (uses your local DB and Redis)
cd backend && uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Start frontend natively
cd frontend && npm run dev
Set SMTP_HOST=localhost and USE_SMTP_IN_DEV=true in backend/.env when running the backend natively so it routes email through the standalone MailHog container.
Stripe webhooks in local development — Stripe cannot reach localhost directly. Install the Stripe CLI and forward events to your local backend:
stripe listen --forward-to localhost:8000/api/v1/stripe/webhook
The CLI prints a signing secret prefixed with whsec_. Copy it into STRIPE_WEBHOOK_SECRET in backend/.env and restart the backend. You can then trigger test events with:
stripe trigger checkout.session.completed

Build docs developers (and LLMs) love

Get started for freeTalk to us