KakeiBuddy Deployment Guide

This guide covers local Docker and Render deployment for the FastAPI backend.

Local Docker Compose

From the repository root:

docker compose up --build

This uses:

Root compose.yaml.
Root Dockerfile.
backend/.env.local through the compose env_file.

The backend is exposed at http://localhost:8000.

Dockerfile Options

There are two backend-oriented Dockerfiles:

File	Purpose
`Dockerfile`	Root image that copies both `backend/` and `model/`, installs AI-related packages, and runs from `/app/backend`
`backend/Dockerfile`	Simpler backend-only image intended for running from the backend directory

Prefer the root Dockerfile when AI policy artifacts from both backend and model directories may be needed. Prefer backend/Dockerfile only when building strictly inside backend/.

Backend Database Modes

The backend chooses database configuration in this order:

DATABASE_URL.
PostgreSQL variables: DB_HOST, DB_USER, DB_PASSWORD or DB_PASSWORD_FILE, DB_NAME, DB_PORT.
Local SQLite fallback: sqlite+aiosqlite:///./sql_app.db.

For production, use PostgreSQL. Local SQLite is best for development only.

Render Deployment

render.yaml defines:

Web service: kakeibuddy-backend.
Runtime: Python.
Root directory: backend.
Region: Singapore.
Start command: uvicorn main:app --host 0.0.0.0 --port $PORT.
Health check: /.
PostgreSQL database: kakeibuddy-db.

Required Render secrets:

ADMIN_PASSWORD
RESEARCH_EXPORT_TOKEN

Generated or linked values:

ADMIN_SECRET_KEY
DATABASE_URL

Production Checklist

Set a strong ADMIN_PASSWORD.
Set ADMIN_SECRET_KEY through the platform.
Set RESEARCH_EXPORT_TOKEN if research export is enabled.
Use PostgreSQL through DATABASE_URL.
Confirm CORS origins in backend/main.py before public release.
Confirm mobile EXPO_PUBLIC_API_URL points to the deployed API.
Verify /, /docs, and /admin after deployment.
Confirm research export access is protected by the token header.

Mobile Build Notes

The Expo app can be run locally with:

cd mobile
npm start

For native development:

npm run android
npm run ios

Before building a production mobile app, configure:

EXPO_PUBLIC_API_URL to the production backend.
App package identifiers in mobile/app.json.
Platform signing credentials through the selected Expo/EAS workflow.

Documentation Site

The documentation website is published from the docs/ folder on the main branch.

GitHub Pages settings:

Source: Deploy from a branch
Branch: main
Folder: /docs
Custom domain: docs.kakeibuddy.me

DNS for the custom domain should include:

Type: CNAME
Name: docs
Value: lizantoinette.github.io

Back to Documentation Home