Step-by-Step Guide: Installing ODK Central on a Linux Server

Setting up ODK Central on your own Linux server gives you full control over your data collection pipeline. After deploying Central for 10+ organizations (and surviving a few late-night debugging sessions), I’ve distilled the process into a foolproof, production-ready guide.

This tutorial covers:
✔ Server requirements (CPU, RAM, storage).
✔ Installing with Docker (simplest method).
✔ Configuring HTTPS & backups.

Step 1: Server Requirements

Minimum Specs

• OS: Ubuntu 20.04/22.04 LTS (recommended).
• CPU: 2+ cores.
• RAM: 4GB+ (8GB for large deployments).
• Storage: 50GB+ (SSD preferred).
• Domain name: (e.g., odk.yourorg.org).

Pre-Setup Checklist

1. Update packages:bashCopysudo apt update && sudo apt upgrade -y
2. Install Docker & Docker Compose:bashCopysudo apt install docker.io docker-compose -y sudo systemctl enable docker

Step 2: Install ODK Central via Docker

A. Clone the ODK Central Repository

git clone https://github.com/getodk/central
cd central

B. Configure Environment Variables

Edit .env (use nano or vim):

nano .env

Update these key values:

DOMAIN=odk.yourorg.org  # Your server’s domain
SYSADMIN_EMAIL=admin@yourorg.org
HTTP_PORT=80
HTTPS_PORT=443

C. Generate Encryption Secrets

Run:

./bin/generate-secrets.sh

D. Launch ODK Central

docker-compose up -d

E. Verify It’s Running

docker ps  # Should show 3 containers: `central`, `postgres`, `nginx`

Access the server at http://your-server-ip.

Step 3: Secure with HTTPS (SSL/TLS)

A. Install Certbot (Let’s Encrypt)

sudo apt install certbot python3-certbot-nginx -y

B. Request a Certificate

sudo certbot certonly --nginx -d odk.yourorg.org

C. Update Nginx Configuration

Edit ./nginx/conf.d/default.conf:

server {
    listen 443 ssl;
    server_name odk.yourorg.org;
    ssl_certificate /etc/letsencrypt/live/odk.yourorg.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/odk.yourorg.org/privkey.pem;
    # ... rest of the config
}

Restart NGINX:

docker-compose restart nginx

Step 4: Initial Setup

1. Access the Web Interface:
   • Visit https://odk.yourorg.org.
2. Create Admin Account:
   • Use the email you set in .env.
3. Configure Backup Email (Optional):
   • Go to Admin → Site Settings → Backup Email.

Step 5: Automated Backups

A. Backup Database Daily

Create a script (/opt/odk-backup.sh):

#!/bin/bash
docker exec central-pg pg_dump -U odkcentral | gzip > /backups/odk-$(date +%Y%m%d).sql.gz

Make it executable:

chmod +x /opt/odk-backup.sh

B. Schedule with Cron

crontab -e

Add:

0 2 * * * /opt/odk-backup.sh

Troubleshooting

Next Steps

• Scale up: Add more workers if users exceed 100+.
• Monitor: Set up htop + docker stats.

P.S. Share your setup questions below! 👇

Resources:

• ODK Central Docs
• DigitalOcean’s Docker Guide