lewis.moe / bspds-sandbox
this repo has no description
fork atom
bspds-sandbox / docs / install-openbsd.md
at 61e33ca7dae83495128e4f850515e54bf64ac1a1 7.7 kB view raw view code

BSPDS Production Installation on OpenBSD#

Warning: These instructions are untested and theoretical, written from the top of Lewis' head. They may contain errors or omissions. This warning will be removed once the guide has been verified. This guide covers installing BSPDS on OpenBSD 7.8 (current release as of December 2025).

Prerequisites#

  • A VPS with at least 2GB RAM and 20GB disk
  • A domain name pointing to your server's IP
  • A wildcard TLS certificate for *.pds.example.com (user handles are served as subdomains)
  • Root access (or doas configured)

Why nginx over relayd?#

OpenBSD's native relayd supports WebSockets but does not support HTTP/2. For a modern PDS deployment, we recommend nginx which provides HTTP/2, WebSocket support, and automatic OCSP stapling.

1. System Setup#

pkg_add curl git

2. Install Rust#

pkg_add rust

OpenBSD 7.8 ships Rust 1.82+. For the latest stable (1.92+), use rustup:

pkg_add rustup
rustup-init -y
source ~/.cargo/env
rustup default stable

3. Install postgres#

OpenBSD 7.8 includes PostgreSQL 17 (PostgreSQL 18 may not yet be in ports):

pkg_add postgresql-server postgresql-client
mkdir -p /var/postgresql/data
chown _postgresql:_postgresql /var/postgresql/data
su - _postgresql -c "initdb -D /var/postgresql/data -U postgres -A scram-sha-256"
rcctl enable postgresql
rcctl start postgresql
psql -U postgres -c "CREATE USER bspds WITH PASSWORD 'your-secure-password';"
psql -U postgres -c "CREATE DATABASE pds OWNER bspds;"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE pds TO bspds;"

4. Install minio#

OpenBSD doesn't have a minio package. Options: Option A: Use an external S3-compatible service (recommended for production) aws s3, backblaze b2, or upcloud managed object storage. Skip to step 5 and configure the S3 credentials in step 9. Option B: Build minio from source

pkg_add go
mkdir -p /tmp/minio-build && cd /tmp/minio-build
ftp -o minio.tar.gz https://github.com/minio/minio/archive/refs/tags/RELEASE.2025-10-15T17-29-55Z.tar.gz
tar xzf minio.tar.gz
cd minio-*
go build -o minio .
cp minio /usr/local/bin/
mkdir -p /var/minio/data
useradd -d /var/minio -s /sbin/nologin _minio
chown -R _minio:_minio /var/minio
cat > /etc/minio.conf << 'EOF'
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-minio-password
EOF
chmod 600 /etc/minio.conf
cat > /etc/rc.d/minio << 'EOF'
#!/bin/ksh
daemon="/usr/local/bin/minio"
daemon_user="_minio"
daemon_flags="server /var/minio/data --console-address :9001"
. /etc/rc.d/rc.subr
rc_pre() {
    . /etc/minio.conf
    export MINIO_ROOT_USER MINIO_ROOT_PASSWORD
}
rc_cmd $1
EOF
chmod +x /etc/rc.d/minio
rcctl enable minio
rcctl start minio

Create the blob bucket:

ftp -o /usr/local/bin/mc https://dl.min.io/client/mc/release/openbsd-amd64/mc
chmod +x /usr/local/bin/mc
mc alias set local http://localhost:9000 minioadmin your-minio-password
mc mb local/pds-blobs

5. Install redis#

OpenBSD has redis in ports (valkey not available yet):

pkg_add redis
rcctl enable redis
rcctl start redis

6. Install deno (for frontend build)#

curl -fsSL https://deno.land/install.sh | sh
export PATH="$HOME/.deno/bin:$PATH"
echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.profile

7. Clone and Build BSPDS#

mkdir -p /opt && cd /opt
git clone https://tangled.org/lewis.moe/bspds-sandbox bspds
cd bspds
cd frontend
deno task build
cd ..
cargo build --release

8. Install sqlx-cli and Run Migrations#

cargo install sqlx-cli --no-default-features --features postgres
export DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds"
sqlx migrate run

9. Configure BSPDS#

mkdir -p /etc/bspds
cp /opt/bspds/.env.example /etc/bspds/bspds.conf
chmod 600 /etc/bspds/bspds.conf

Edit /etc/bspds/bspds.conf and fill in your values. Generate secrets with:

openssl rand -base64 48

10. Create rc.d Service#

useradd -d /var/empty -s /sbin/nologin _bspds
cp /opt/bspds/target/release/bspds /usr/local/bin/
mkdir -p /var/bspds
cp -r /opt/bspds/frontend/dist /var/bspds/frontend
chown -R _bspds:_bspds /var/bspds
cat > /etc/rc.d/bspds << 'EOF'
#!/bin/ksh
daemon="/usr/local/bin/bspds"
daemon_user="_bspds"
daemon_logger="daemon.info"
. /etc/rc.d/rc.subr
rc_pre() {
    export FRONTEND_DIR=/var/bspds/frontend
    while IFS='=' read -r key value; do
        case "$key" in
            \#*|"") continue ;;
        esac
        export "$key=$value"
    done < /etc/bspds/bspds.conf
}
rc_cmd $1
EOF
chmod +x /etc/rc.d/bspds
rcctl enable bspds
rcctl start bspds

11. Install and Configure nginx#

pkg_add nginx
cat > /etc/nginx/nginx.conf << 'EOF'
worker_processes 1;
events {
    worker_connections 1024;
}
http {
    include mime.types;
    server {
        listen 80;
        listen [::]:80;
        server_name pds.example.com;
        location /.well-known/acme-challenge/ {
            root /var/www/acme;
        }
        location / {
            return 301 https://$host$request_uri;
        }
    }
    server {
        listen 443 ssl http2;
        listen [::]:443 ssl http2;
        server_name pds.example.com;
        ssl_certificate /etc/ssl/pds.example.com.fullchain.pem;
        ssl_certificate_key /etc/ssl/private/pds.example.com.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL:10m;
        location / {
            proxy_pass http://127.0.0.1:3000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_read_timeout 86400;
        }
    }
}
EOF
mkdir -p /var/www/acme
rcctl enable nginx

12. Obtain Wildcard SSL Certificate#

User handles are served as subdomains (e.g., alice.pds.example.com), so you need a wildcard certificate.

OpenBSD's native acme-client only supports HTTP-01 validation, which can't issue wildcard certs. You have a few options:

Option A: Use certbot with DNS validation (recommended)

pkg_add certbot
certbot certonly --manual --preferred-challenges dns \
  -d pds.example.com -d '*.pds.example.com'

Follow the prompts to add TXT records to your DNS. Then update nginx.conf to point to the certbot certs.

Option B: Use a managed DNS provider with API If your DNS provider has a certbot plugin, you can automate renewal.

Option C: Use acme.sh acme.sh supports many DNS providers for automated wildcard cert renewal.

After obtaining the cert, update nginx to use it and restart:

rcctl restart nginx

13. Configure Packet Filter (pf)#

cat >> /etc/pf.conf << 'EOF'
pass in on egress proto tcp from any to any port { 22, 80, 443 }
EOF
pfctl -f /etc/pf.conf

14. Verify Installation#

rcctl check bspds
ftp -o - https://pds.example.com/xrpc/_health
ftp -o - https://pds.example.com/.well-known/atproto-did

Maintenance#

View logs:

tail -f /var/log/daemon

Update BSPDS:

cd /opt/bspds
git pull
cd frontend && deno task build && cd ..
cargo build --release
rcctl stop bspds
cp target/release/bspds /usr/local/bin/
cp -r frontend/dist /var/bspds/frontend
DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds" sqlx migrate run
rcctl start bspds

Backup database:

pg_dump -U postgres pds > /var/backups/pds-$(date +%Y%m%d).sql