Skip to content

one-click-deploy.md

Latest commit

 

History

History
161 lines (108 loc) · 5.56 KB

one-click-deploy.md

File metadata and controls

161 lines (108 loc) · 5.56 KB
Raw

One-Click Cloud Deploy

Deploy CareLoom to a managed cloud platform without managing servers. This guide covers Railway (recommended) and Render.

What You Get

A running CareLoom instance with:

  • API service (Spring Boot) connected to a managed MySQL database
  • Admin dashboard (React) accessible via browser
  • Default admin account for initial setup

The mobile app is not deployed to the cloud. CHWs install it on their Android devices and point it at the API URL.

Railway (Recommended)

Estimated cost: ~$5-8/month (Hobby plan, varies with usage) Time: ~5 minutes

Railway provides managed MySQL and easy multi-service deploys from a mono-repo.

Step 1: Create a Railway Project

  1. Go to railway.app and sign in with GitHub
  2. Click New Project > Deploy from GitHub repo
  3. Select the DHEPLab/careloom repository (fork it first if needed)

Step 2: Add MySQL

  1. In your project dashboard, click New > Database > MySQL
  2. Railway auto-provisions the database and sets MYSQL_* environment variables
  3. Note: the database is empty at this point. The API will run Flyway migrations on first boot.

Step 3: Create the API Service

  1. Click New > GitHub Repo > select the same repo
  2. In the service settings:
    • Root Directory: services/api
    • Builder: Dockerfile
  3. Add these environment variables (Settings > Variables):
Variable Value
SPRING_PROFILES_ACTIVE docker
SPRING_DATASOURCE_URL jdbc:mysql://${{MySQL.MYSQLHOST}}:${{MySQL.MYSQLPORT}}/${{MySQL.MYSQLDATABASE}}?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=utf-8
SPRING_DATASOURCE_USERNAME ${{MySQL.MYSQLUSER}}
SPRING_DATASOURCE_PASSWORD ${{MySQL.MYSQLPASSWORD}}
JWT_SECRET_KEY Generate a strong random string (e.g., openssl rand -hex 32)
  1. Set the Port to 8080
  2. Set the Health Check Path to /actuator/health
  3. Click Deploy

Step 4: Create the Admin Dashboard Service

  1. Click New > GitHub Repo > select the same repo again
  2. In the service settings:
    • Root Directory: services/admin-web
    • Builder: Dockerfile
  3. Add this environment variable:
Variable Value
API_URL http://careloom-api.railway.internal:8080
  1. Set the Port to 3000
  2. Click Deploy

Step 5: Generate Public URLs

  1. For each service, go to Settings > Networking > Generate Domain
  2. The admin dashboard URL is what you'll share with program managers
  3. The API URL is what you'll configure in the mobile app

Render

Estimated cost: ~$14-21/month (two Starter instances + external MySQL) Time: ~10 minutes

Important: Render Does Not Offer Managed MySQL

You must provision MySQL separately. Options:

  • PlanetScale (free tier available, MySQL-compatible)
  • Aiven (free tier, managed MySQL)
  • Any MySQL 5.7+ provider

Step 1: Provision External MySQL

  1. Create a MySQL 5.7+ database on your chosen provider
  2. Note the connection details: host, port, database name, username, password

Step 2: Deploy with Render Blueprint

  1. Go to render.com and sign in
  2. Click New > Blueprint
  3. Connect the DHEPLab/careloom repository
  4. Render reads render.yaml and creates two services automatically

Step 3: Set Database Variables

For the careloom-api service, set these environment variables manually:

Variable Value
SPRING_DATASOURCE_URL jdbc:mysql://YOUR_HOST:3306/YOUR_DB?useSSL=true&characterEncoding=utf-8
SPRING_DATASOURCE_USERNAME Your MySQL username
SPRING_DATASOURCE_PASSWORD Your MySQL password

The JWT_SECRET_KEY is auto-generated by the Blueprint.

Step 4: Deploy

  1. Click Apply to deploy both services
  2. Wait for the API health check to pass (may take 1-2 minutes on first boot as Flyway runs migrations)

Post-Deployment Steps

1. Change Default Passwords

Log in to the admin dashboard with the default credentials (admin / admin) and immediately change the password.

2. Load a Curriculum

CareLoom ships with no curriculum data. Use the admin dashboard to:

  1. Create a new Curriculum
  2. Add Modules with content components (text, media, switches)
  3. Assign the curriculum to a Project

3. Configure the Mobile App

Point the mobile app at your API URL:

  1. In services/app, update the API endpoint configuration
  2. Build the APK with npx expo build:android or use EAS Build
  3. Distribute to CHWs

4. Custom Domain (Optional)

Both Railway and Render support custom domains:

  • Railway: Settings > Networking > Custom Domain
  • Render: Settings > Custom Domains

Troubleshooting

API fails health check on first deploy

The first boot takes longer because Flyway runs all 62 database migrations. Wait 2-3 minutes and check logs. If it still fails, verify your database connection string.

"Access denied" database errors

Double-check SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD. On Railway, make sure you're using the ${{MySQL.MYSQLUSER}} variable reference, not a hardcoded value.

Admin dashboard shows "Network Error"

The API_URL environment variable must point to the API's internal URL (not the public URL). On Railway, use http://careloom-api.railway.internal:8080.

Mobile app can't connect to API

The mobile app needs the API's public URL (the one with the Railway/Render domain). Make sure CORS is configured if you're using a custom domain.