this repo has no description
lewis.moe
1# BSPDS Production Installation on OpenBSD
2> **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.
3This guide covers installing BSPDS on OpenBSD 7.8 (current release as of December 2025).
4## Prerequisites
5- A VPS with at least 2GB RAM and 20GB disk
6- A domain name pointing to your server's IP
7- A **wildcard TLS certificate** for `*.pds.example.com` (user handles are served as subdomains)
8- Root access (or doas configured)
9## Why nginx over relayd?
10OpenBSD'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.
11## 1. System Setup
12```sh
13pkg_add curl git
14```
15## 2. Install Rust
16```sh
17pkg_add rust
18```
19OpenBSD 7.8 ships Rust 1.82+. For the latest stable (1.92+), use rustup:
20```sh
21pkg_add rustup
22rustup-init -y
23source ~/.cargo/env
24rustup default stable
25```
26## 3. Install postgres
27OpenBSD 7.8 includes PostgreSQL 17 (PostgreSQL 18 may not yet be in ports):
28```sh
29pkg_add postgresql-server postgresql-client
30mkdir -p /var/postgresql/data
31chown _postgresql:_postgresql /var/postgresql/data
32su - _postgresql -c "initdb -D /var/postgresql/data -U postgres -A scram-sha-256"
33rcctl enable postgresql
34rcctl start postgresql
35psql -U postgres -c "CREATE USER bspds WITH PASSWORD 'your-secure-password';"
36psql -U postgres -c "CREATE DATABASE pds OWNER bspds;"
37psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE pds TO bspds;"
38```
39## 4. Install minio
40OpenBSD doesn't have a minio package. Options:
41**Option A: Use an external S3-compatible service (recommended for production)**
42aws s3, backblaze b2, or upcloud managed object storage. Skip to step 5 and configure the S3 credentials in step 9.
43**Option B: Build minio from source**
44```sh
45pkg_add go
46mkdir -p /tmp/minio-build && cd /tmp/minio-build
47ftp -o minio.tar.gz https://github.com/minio/minio/archive/refs/tags/RELEASE.2025-10-15T17-29-55Z.tar.gz
48tar xzf minio.tar.gz
49cd minio-*
50go build -o minio .
51cp minio /usr/local/bin/
52mkdir -p /var/minio/data
53useradd -d /var/minio -s /sbin/nologin _minio
54chown -R _minio:_minio /var/minio
55cat > /etc/minio.conf << 'EOF'
56MINIO_ROOT_USER=minioadmin
57MINIO_ROOT_PASSWORD=your-minio-password
58EOF
59chmod 600 /etc/minio.conf
60cat > /etc/rc.d/minio << 'EOF'
61#!/bin/ksh
62daemon="/usr/local/bin/minio"
63daemon_user="_minio"
64daemon_flags="server /var/minio/data --console-address :9001"
65. /etc/rc.d/rc.subr
66rc_pre() {
67 . /etc/minio.conf
68 export MINIO_ROOT_USER MINIO_ROOT_PASSWORD
69}
70rc_cmd $1
71EOF
72chmod +x /etc/rc.d/minio
73rcctl enable minio
74rcctl start minio
75```
76Create the blob bucket:
77```sh
78ftp -o /usr/local/bin/mc https://dl.min.io/client/mc/release/openbsd-amd64/mc
79chmod +x /usr/local/bin/mc
80mc alias set local http://localhost:9000 minioadmin your-minio-password
81mc mb local/pds-blobs
82```
83## 5. Install redis
84OpenBSD has redis in ports (valkey not available yet):
85```sh
86pkg_add redis
87rcctl enable redis
88rcctl start redis
89```
90## 6. Install deno (for frontend build)
91```sh
92curl -fsSL https://deno.land/install.sh | sh
93export PATH="$HOME/.deno/bin:$PATH"
94echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.profile
95```
96## 7. Clone and Build BSPDS
97```sh
98mkdir -p /opt && cd /opt
99git clone https://tangled.org/lewis.moe/bspds-sandbox bspds
100cd bspds
101cd frontend
102deno task build
103cd ..
104cargo build --release
105```
106## 8. Install sqlx-cli and Run Migrations
107```sh
108cargo install sqlx-cli --no-default-features --features postgres
109export DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds"
110sqlx migrate run
111```
112## 9. Configure BSPDS
113```sh
114mkdir -p /etc/bspds
115cp /opt/bspds/.env.example /etc/bspds/bspds.conf
116chmod 600 /etc/bspds/bspds.conf
117```
118Edit `/etc/bspds/bspds.conf` and fill in your values. Generate secrets with:
119```sh
120openssl rand -base64 48
121```
122## 10. Create rc.d Service
123```sh
124useradd -d /var/empty -s /sbin/nologin _bspds
125cp /opt/bspds/target/release/bspds /usr/local/bin/
126mkdir -p /var/bspds
127cp -r /opt/bspds/frontend/dist /var/bspds/frontend
128chown -R _bspds:_bspds /var/bspds
129cat > /etc/rc.d/bspds << 'EOF'
130#!/bin/ksh
131daemon="/usr/local/bin/bspds"
132daemon_user="_bspds"
133daemon_logger="daemon.info"
134. /etc/rc.d/rc.subr
135rc_pre() {
136 export FRONTEND_DIR=/var/bspds/frontend
137 while IFS='=' read -r key value; do
138 case "$key" in
139 \#*|"") continue ;;
140 esac
141 export "$key=$value"
142 done < /etc/bspds/bspds.conf
143}
144rc_cmd $1
145EOF
146chmod +x /etc/rc.d/bspds
147rcctl enable bspds
148rcctl start bspds
149```
150## 11. Install and Configure nginx
151```sh
152pkg_add nginx
153cat > /etc/nginx/nginx.conf << 'EOF'
154worker_processes 1;
155events {
156 worker_connections 1024;
157}
158http {
159 include mime.types;
160 server {
161 listen 80;
162 listen [::]:80;
163 server_name pds.example.com;
164 location /.well-known/acme-challenge/ {
165 root /var/www/acme;
166 }
167 location / {
168 return 301 https://$host$request_uri;
169 }
170 }
171 server {
172 listen 443 ssl http2;
173 listen [::]:443 ssl http2;
174 server_name pds.example.com;
175 ssl_certificate /etc/ssl/pds.example.com.fullchain.pem;
176 ssl_certificate_key /etc/ssl/private/pds.example.com.key;
177 ssl_protocols TLSv1.2 TLSv1.3;
178 ssl_ciphers HIGH:!aNULL:!MD5;
179 ssl_prefer_server_ciphers on;
180 ssl_session_cache shared:SSL:10m;
181 location / {
182 proxy_pass http://127.0.0.1:3000;
183 proxy_http_version 1.1;
184 proxy_set_header Upgrade $http_upgrade;
185 proxy_set_header Connection "upgrade";
186 proxy_set_header Host $host;
187 proxy_set_header X-Real-IP $remote_addr;
188 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
189 proxy_set_header X-Forwarded-Proto $scheme;
190 proxy_read_timeout 86400;
191 }
192 }
193}
194EOF
195mkdir -p /var/www/acme
196rcctl enable nginx
197```
198## 12. Obtain Wildcard SSL Certificate
199User handles are served as subdomains (e.g., `alice.pds.example.com`), so you need a wildcard certificate.
200
201OpenBSD's native `acme-client` only supports HTTP-01 validation, which can't issue wildcard certs. You have a few options:
202
203**Option A: Use certbot with DNS validation (recommended)**
204```sh
205pkg_add certbot
206certbot certonly --manual --preferred-challenges dns \
207 -d pds.example.com -d '*.pds.example.com'
208```
209Follow the prompts to add TXT records to your DNS. Then update nginx.conf to point to the certbot certs.
210
211**Option B: Use a managed DNS provider with API**
212If your DNS provider has a certbot plugin, you can automate renewal.
213
214**Option C: Use acme.sh**
215[acme.sh](https://github.com/acmesh-official/acme.sh) supports many DNS providers for automated wildcard cert renewal.
216
217After obtaining the cert, update nginx to use it and restart:
218```sh
219rcctl restart nginx
220```
221## 13. Configure Packet Filter (pf)
222```sh
223cat >> /etc/pf.conf << 'EOF'
224pass in on egress proto tcp from any to any port { 22, 80, 443 }
225EOF
226pfctl -f /etc/pf.conf
227```
228## 14. Verify Installation
229```sh
230rcctl check bspds
231ftp -o - https://pds.example.com/xrpc/_health
232ftp -o - https://pds.example.com/.well-known/atproto-did
233```
234## Maintenance
235View logs:
236```sh
237tail -f /var/log/daemon
238```
239Update BSPDS:
240```sh
241cd /opt/bspds
242git pull
243cd frontend && deno task build && cd ..
244cargo build --release
245rcctl stop bspds
246cp target/release/bspds /usr/local/bin/
247cp -r frontend/dist /var/bspds/frontend
248DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds" sqlx migrate run
249rcctl start bspds
250```
251Backup database:
252```sh
253pg_dump -U postgres pds > /var/backups/pds-$(date +%Y%m%d).sql
254```