VPS configuration

This repo contains the playbooks used to configure a VPS and a second host (Raspberry Pi over Tailscale), and to deploy the splintercom/Intercom app stack to production.

Setup

In order to run these playbooks you'll need some prerequisites. First, we need an ansible vault file to contain our secrets. This can go into group_vars/all.yml with the following keys:

VAULTWARDEN_YUBICO_CLIENT_ID: <client ID>
VAULTWARDEN_YUBICO_SECRET_KEY: <secret key>
VAULTWARDEN_PRIMARY_DOMAIN: <domain>
VAULTWARDEN_SECONDARY_DOMAIN: <domain>
VAULTWARDEN_REMOTE_BACKUP_HOST: <host fqdn>
ADMIN_EMAIL: <email>
TAILSCALE_AUTHKEY: <key>

# splintercom / Intercom stack
SPLINTERCOM_DOMAIN: <domain>
POSTGRES_HOST: postgres_db
POSTGRES_DB: <db>
POSTGRES_USER: <user>
POSTGRES_PASSWORD: <password>
DJANGO_SECRET_KEY: <key>
DJANGO_SUPERUSER_EMAIL: <email>
DJANGO_SUPERUSER_PASSWORD: <password>
DJANGO_ALLOWED_HOSTS: <comma-separated>
DJANGO_CSRF_TRUSTED_ORIGINS: <comma-separated>
AWS_ACCESS_KEY_ID: <key>
AWS_SECRET_ACCESS_KEY: <secret>
AWS_ACCOUNT_ID: <id>
COGNITO_DOMAIN: <domain>
COGNITO_USER_POOL_ID: <id>
COGNITO_APP_CLIENT_ID: <id>
COGNITO_APP_CLIENT_SECRET: <secret>
COTURN_SECRET: <secret>
DOCKER_REGISTRY_USER: <user>
DOCKER_REGISTRY_PASSWORD: <password>
HONEYCOMB_API_KEY: <key>   # production Honeycomb environment key

Next, we need a host file with the following format:

[vaultwarden:children]
vps
pi

[pi]
<tailscale raspberry pi fqdn>

[vps]
<VPS fqdn >

You will also need an ssh key for connecting to both hosts mentioned in the hosts file.

Lastly, for convenience it helps to create a password file for our vault secret file in group_vars/all.yml. Filename vault_password_file is already included in .gitignore

Bootstrapping

The playbooks included in this repo assume that there is an ansible sudo use present to run sudo commands. This user can be setup by running the bootstrap.yml playbook first.

Additional Steps

Currently, remote backups require a .ssh/config file and an ssh key under the ansible user to allow the primary host to ssh/rsync to the secondary.

Running the playbooks

Assuming the above prerequisites have been met, the playbooks can be run in check mode as follows:

ansible-playbook -i hosts deploy.yml --private-key id_rsa --vault-password-file vault_password_file --check

Drop --check to apply. The splintercom app stack is deployed separately:

ansible-playbook -i hosts deploy_splintercom.yml --private-key id_rsa --vault-password-file vault_password_file

The splintercom stack is provisioned by the splintercom.splintercom collection, split into one role per service (postgres, coturn, backend, frontend). It's sourced from Splintercom/AnsibleSpintercomCollection via requirements.yml — install it (and the other collection/role dependencies) before running the playbooks:

ansible-galaxy install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

CI/CD Deployment

.github/workflows/deploy_splintercom.yaml automates the splintercom deploy via workflow_dispatch (manual trigger with a tag input). Runs on the self-hosted VPS runner. Writes secrets from GitHub Actions secrets (ANSIBLE_INVENTORY, ANSIBLE_VAULT_PASSWORD, ANSIBLE_VAULT_VARS, DEPLOY_SSH_KEY) into local files, runs the Ansible playbook, then cleans up. The HONEYCOMB_API_KEY secret should also be set here to enable CI metrics in Honeycomb.