Self-Hosting CO-OP

CO-OP is open source and can be self-hosted on your own server. This guide walks you through setting up your own instance.

Requirements

To run CO-OP, you’ll need:

• A server with Docker and Docker Compose installed
• A domain name pointing to your server
• Basic familiarity with command line and Docker
• An email service provider (Mailgun recommended)

Minimum server specs

• 1 GB RAM
• 1 CPU core
• 10 GB disk space

Architecture overview

CO-OP consists of several services:

All services are containerized and orchestrated with Docker Compose.

Quick start

1. Clone the repository

git clone https://github.com/allanlasser/co-op.computer.git
cd co-op.computer

2. Configure environment variables

Copy the example environment file and edit it:

cp .env.example .env.production

Edit .env.production with your settings:

# Django settings
DEBUG=False
SECRET_KEY=your-secure-random-secret-key
ALLOWED_HOSTS=your-domain.com
CSRF_TRUSTED_ORIGINS=https://your-domain.com

# Database (internal to Docker network)
POSTGRES_DB=coop
POSTGRES_USER=coop
POSTGRES_PASSWORD=your-secure-db-password

# Redis (internal to Docker network)
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Email (Mailgun)
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_SENDER_DOMAIN=your-mailgun-domain.com
DEFAULT_FROM_EMAIL=noreply@your-domain.com

# Frontend (baked into build)
PUBLIC_API_URL=https://your-domain.com/api

# Optional: Error monitoring
SENTRY_DSN_BACKEND=
SENTRY_DSN_FRONTEND=

3. Update the Caddyfile

Edit the Caddyfile to use your domain:

your-domain.com {
    # API routes
    handle /api/* {
        reverse_proxy backend:8000
    }

    handle /admin/* {
        reverse_proxy backend:8000
    }

    # Static files
    handle /static/* {
        reverse_proxy backend:8000
    }

    handle /media/* {
        reverse_proxy backend:8000
    }

    # Frontend
    handle {
        reverse_proxy frontend:3000
    }
}

4. Build and start the services

docker-compose --env-file .env.production -f docker-compose.prod.yml up -d --build

This will:

• Build the Docker images
• Start all services
• Run database migrations automatically
• Configure HTTPS via Let’s Encrypt

5. Create an admin user

docker-compose -f docker-compose.prod.yml exec backend python manage.py createsuperuser

6. Access your instance

• Frontend: https://your-domain.com
• Admin panel: https://your-domain.com/admin

Configuration details

Email setup (Mailgun)

CO-OP uses Mailgun for sending emails (invitations, notifications, etc.). You’ll need:

1. A Mailgun account (free tier available)
2. A verified sending domain
3. Your API key

Configure these in your .env.production:

MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAILGUN_SENDER_DOMAIN=mg.your-domain.com
DEFAULT_FROM_EMAIL=CO-OP <noreply@your-domain.com>

Database backups

The PostgreSQL data is stored in a Docker volume. To back up:

docker-compose -f docker-compose.prod.yml exec postgres pg_dump -U coop coop > backup.sql

To restore:

cat backup.sql | docker-compose -f docker-compose.prod.yml exec -T postgres psql -U coop coop

Updating CO-OP

To update to the latest version:

git pull origin main
docker-compose --env-file .env.production -f docker-compose.prod.yml pull
docker-compose --env-file .env.production -f docker-compose.prod.yml up -d
docker image prune -f

Migrations run automatically when the backend container starts.

Troubleshooting

Viewing logs

# All services
docker-compose -f docker-compose.prod.yml logs -f

# Specific service
docker-compose -f docker-compose.prod.yml logs -f backend

Common issues

HTTPS not working

• Ensure your domain’s DNS is pointing to your server
• Check that ports 80 and 443 are open
• Caddy needs to reach Let’s Encrypt servers

Emails not sending

• Verify your Mailgun API key and domain
• Check the Celery worker logs for errors
• Ensure your domain is verified in Mailgun

Database connection errors

• Wait a moment—the database might still be starting
• Check that PostgreSQL credentials match between services

Security considerations

When self-hosting, keep in mind:

• Keep your server updated with security patches
• Use strong passwords for the database and admin accounts
• Back up regularly and test your backup restoration process
• Monitor your logs for suspicious activity
• Limit admin access to trusted users only

Getting help

If you run into issues:

• Check the GitHub Issues for known problems
• Open a new issue with details about your setup and the error you’re seeing