Install & Update

Install

Local development (MacOS)

1. Install Colima with the Loki driver with Homebrew:

   ./scripts/local/install.sh
   

2. Set up environment variables (see Environment variables):

   cp .env.example .env
   

3. Start your containers:

   ./scripts/local/start.sh
   

4. Initialize your database once the containers are up:

   ./scripts/local/db-migrate.sh
   

5. (Optional) Start ngrok:

   ./scripts/local/ngrok.sh
   

Start the app with ./scripts/local/start.sh. You can clean up your local dev environment (files, Docker images/networks, ...) with ./scripts/local/clean.sh.

You can also use:

• ./scripts/local/db-reset.sh to drop the database and start fresh.
• ./scripts/local/db-generate.sh to generate a new migration file if you've made changes to the models.

Production

Create the server

If you use Hetzner, simply do the following:

1. Add your Hetzner API key:

   cp .env.devops.example .env.devops
   

2. Create the server on Hetzner. You will be prompted for size and location, CPX31 being the recommended default:

   ./scripts/prod/create.sh
   

3. Set up the IP address. Just add the IP address you got from Hetzner to the .env.devops file (SERVER_IP).

If you're not using Hetzner:

1. Create the server,
2. Add your SSH keys and make sure your account has sudo privileges,
3. Set up the IP address. Add the IP address to env.devops as SERVER_IP.

Set up the server

./scripts/prod/setup.sh

Deploy /dev/push

1. Set up environment variables (see Environment variables). Do not forget to set the GitHub repository (GITHUB_REPO) and Let's Encrypt email (LE_EMAIL) for the SSL setup:

   cp .env.prod.example .env.prod
   

2. Deploy and start the app:

   ./scripts/prod/deploy.sh
   

3. Initialize your database once the containers are up:

   ./scripts/prod/db-migrate.sh
   

Update

Local development (MacOS)

The app is mounted inside of its container, so any change will show up immediately. However, certain parts of the app are using SSE so changes may not appear until you closed the tabs with the app open (FastAPI won't reload until all active connections are closed).

The worker is also mounted but will usually require a restart: docker-compose restart worker.

Production

Run ./scripts/prod/update.sh and select whether you want to update the app container, the worker containers, the access list or the runners (Docker images that match the runtimes).

For containers, it will run a blue-green update process via Ansible (no downtime). For the worker containers specifically, this may take a while as it waits for all active jobs to be finished before cleaning up the old container.

Environment variables

GitHub App

You will need to configure a GitHub App with the following settings:

• Identifying and authorizing users:
  • Callback URL: add two callback URLs with your domain:
    • https://example.com/api/github/authorize/callback
    • https://example.com/auth/github/callback
  • Expire user authorization tokens: No
• Post installation:
  • Setup URL: https://example.com/api/github/install/callback
  • Redirect on update: Yes
• Webhook:
  • Active: Yes
  • Webhook URL: https://example.com/api/github/webhook
• Permissions:
  • Repository permissions
    • Administration: Read and write
    • Checks: Read and write
    • Commit statuses: Read and write
    • Contents: Read and write
    • Deployments: Read and write
    • Issues: Read and write
    • Metadata: Read-only
    • Pull requests: Read and write
    • Webhook: Read and write
  • Account permissions:
    • Email addresses: Read-only
• Subscribe to events:
  • Installation target
  • Push
  • Repository

Sign-in access control

You can restrict who can sign up/sign in by adding an access rules file:

cp access.example.json access.json

The file can contain a list of emails, a list of allowed email domains, globs and regexes:

{
  "emails": ["[email protected]"],
  "domains": ["example.com"],
  "globs": ["*@corp.local", "*.dept.example.com"],
  "regex": ["^[^@]+@(eng|research)\\.example\\.com$"]
}

Globs use shell-style wildcards, regex are Python patterns. If the rules file is missing or empty, all valid emails are allowed.

Additionally, if you set the ACCESS_EMAIL_DENIED_WEBHOOK_URL environment variable, denied sign-in attempts will be posted to the provided URL with the following payload:

{
  "email": "[email protected]",
  "provider": "google",
  "ip": "203.0.113.10",
  "user_agent": "Mozilla/5.0"
}