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.

The recommended production topology for Maleku System splits infrastructure across two managed platforms: Railway runs the FastAPI backend alongside its PostgreSQL database and Redis cache, while Vercel serves the Nuxt.js 3 frontend via its global edge network. This split lets each tier scale independently and keeps operational costs predictable — approximately $40/month for a production-grade setup.

​
Architecture

Railway — Backend

Hosts the FastAPI application, PostgreSQL 16 database, and Redis 7 cache. Railway automatically provisions DATABASE_URL and REDIS_URL and injects them into your service environment at runtime.

Vercel — Frontend

Hosts the Nuxt.js 3 SSR/static frontend. Vercel’s edge network distributes the built output globally and provides automatic preview deployments for every pull request.

​
Deploy Backend to Railway

Railway automatically injects DATABASE_URL and REDIS_URL from the PostgreSQL and Redis services you provision into the same project. Do not set these values manually in the Variables tab — doing so will override Railway’s internal connection strings.
1

Install Railway CLI and log in

npm install -g @railway/cli
railway login
2

Initialise the Railway project

Navigate to the backend directory and create a new Railway project. When prompted, select Create a new project and name it costarica-backend.
cd backend
railway init
3

Provision PostgreSQL

railway add --database postgres
Alternatively, open the Railway dashboard, click New → Database → Add PostgreSQL.
4

Provision Redis

railway add --database redis
5

Configure environment variables

In the Railway dashboard, open your backend service and go to the Variables tab. Add the following variables at minimum:
ENVIRONMENT=production
DEBUG=False
SECRET_KEY=<random-string-min-32-chars>
SITE_URL=https://your-frontend.vercel.app
BACKEND_CORS_ORIGINS=["https://your-frontend.vercel.app"]
RESEND_API_KEY=<your-resend-key>
CLOUDINARY_CLOUD_NAME=<your-cloud-name>
CLOUDINARY_API_KEY=<your-cloudinary-api-key>
CLOUDINARY_API_SECRET=<your-cloudinary-api-secret>
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
See Environment Variables for the full reference.
6

Deploy the backend

From inside the backend directory:
railway up
Railway builds the Docker image, pushes it, and starts the service. Monitor the build logs in the dashboard until the deploy shows Active.
7

Run database migrations

After the service is healthy, apply Alembic migrations against the provisioned PostgreSQL instance:
railway run alembic upgrade head
8

Get the backend URL

railway domain
Copy the printed URL (e.g. https://costarica-backend.up.railway.app). You will need it when configuring the frontend.
Run railway domain before starting the Vercel deployment so you have the exact backend URL ready to paste into NUXT_PUBLIC_API_URL. The URL follows the pattern https://<project-name>.up.railway.app.

​
Deploy Frontend to Vercel

1

Update vercel.json with the Railway backend URL

Open frontend/vercel.json and replace the placeholder values:
  • your-railway-app-url → the URL from railway domain
  • your-vercel-domain → your custom domain (optional)
2

Log in to Vercel and link the project

cd frontend
vercel login
vercel link
3

Set frontend environment variables

In the Vercel dashboard go to Settings → Environment Variables and add:
NUXT_PUBLIC_API_URL=https://your-backend.up.railway.app/api/v1
NUXT_PUBLIC_SITE_URL=https://your-frontend.vercel.app
These are the only two variables the Nuxt.js app requires at build and runtime.
4

Deploy to production

vercel --prod
Vercel builds the Nuxt.js application and publishes it to the edge network. The deploy URL is printed on completion.

​
Automated Deployment Script

The repository ships a deploy.sh script that wraps the Railway and Vercel CLI steps above: 
# Deploy only the backend
./deploy.sh backend

# Deploy only the frontend
./deploy.sh frontend

# Deploy both in sequence
./deploy.sh all
The script checks that the respective CLI tools are installed (installing them if missing) and that you are already authenticated before proceeding.

​
Post-Deployment Checklist

After both services are live, complete the following steps:
  • Stripe webhook — In the Stripe Dashboard, create a webhook pointing to https://your-backend.up.railway.app/api/v1/stripe/webhook and subscribe to checkout.session.completed and invoice.paid.
  • Resend domain — Verify the costaricatravel.dev sender domain in Resend and configure SPF/DKIM DNS records.
  • CORS validation — Confirm BACKEND_CORS_ORIGINS includes the exact Vercel URL with https:// and no trailing slash.
  • Health check — Run curl https://your-backend.up.railway.app/health to confirm the API is responding.

Build docs developers (and LLMs) love

Get started for freeTalk to us