this repo has no description
lewis.moe
1# BSPDS Production Installation on Debian
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.
3
4This guide covers installing BSPDS on Debian 13 "Trixie" (current stable as of December 2025).
5
6## Prerequisites
7- A VPS with at least 2GB RAM and 20GB disk
8- A domain name pointing to your server's IP
9- A **wildcard TLS certificate** for `*.pds.example.com` (user handles are served as subdomains)
10- Root or sudo access
11## 1. System Setup
12```bash
13apt update && apt upgrade -y
14apt install -y curl git build-essential pkg-config libssl-dev
15```
16## 2. Install Rust
17```bash
18curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
19source ~/.cargo/env
20rustup default stable
21```
22This installs the latest stable Rust (1.92+ as of December 2025).
23## 3. Install postgres
24Debian 13 includes PostgreSQL 17:
25```bash
26apt install -y postgresql postgresql-contrib
27systemctl enable postgresql
28systemctl start postgresql
29sudo -u postgres psql -c "CREATE USER bspds WITH PASSWORD 'your-secure-password';"
30sudo -u postgres psql -c "CREATE DATABASE pds OWNER bspds;"
31sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE pds TO bspds;"
32```
33## 4. Install minio
34```bash
35curl -O https://dl.min.io/server/minio/release/linux-amd64/minio
36chmod +x minio
37mv minio /usr/local/bin/
38mkdir -p /var/lib/minio/data
39useradd -r -s /sbin/nologin minio-user
40chown -R minio-user:minio-user /var/lib/minio
41cat > /etc/default/minio << 'EOF'
42MINIO_ROOT_USER=minioadmin
43MINIO_ROOT_PASSWORD=your-minio-password
44MINIO_VOLUMES="/var/lib/minio/data"
45MINIO_OPTS="--console-address :9001"
46EOF
47cat > /etc/systemd/system/minio.service << 'EOF'
48[Unit]
49Description=MinIO Object Storage
50After=network.target
51[Service]
52User=minio-user
53Group=minio-user
54EnvironmentFile=/etc/default/minio
55ExecStart=/usr/local/bin/minio server $MINIO_VOLUMES $MINIO_OPTS
56Restart=always
57LimitNOFILE=65536
58[Install]
59WantedBy=multi-user.target
60EOF
61systemctl daemon-reload
62systemctl enable minio
63systemctl start minio
64```
65Create the blob bucket (wait a few seconds for minio to start):
66```bash
67curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
68chmod +x mc
69mv mc /usr/local/bin/
70mc alias set local http://localhost:9000 minioadmin your-minio-password
71mc mb local/pds-blobs
72```
73## 5. Install valkey
74Debian 13 includes Valkey 8:
75```bash
76apt install -y valkey
77systemctl enable valkey-server
78systemctl start valkey-server
79```
80## 6. Install deno (for frontend build)
81```bash
82curl -fsSL https://deno.land/install.sh | sh
83export PATH="$HOME/.deno/bin:$PATH"
84echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
85```
86## 7. Clone and Build BSPDS
87```bash
88cd /opt
89git clone https://tangled.org/lewis.moe/bspds-sandbox bspds
90cd bspds
91cd frontend
92deno task build
93cd ..
94cargo build --release
95```
96## 8. Install sqlx-cli and Run Migrations
97```bash
98cargo install sqlx-cli --no-default-features --features postgres
99export DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds"
100sqlx migrate run
101```
102## 9. Configure BSPDS
103```bash
104mkdir -p /etc/bspds
105cp /opt/bspds/.env.example /etc/bspds/bspds.env
106chmod 600 /etc/bspds/bspds.env
107```
108Edit `/etc/bspds/bspds.env` and fill in your values. Generate secrets with:
109```bash
110openssl rand -base64 48
111```
112## 10. Create Systemd Service
113```bash
114useradd -r -s /sbin/nologin bspds
115cp /opt/bspds/target/release/bspds /usr/local/bin/
116mkdir -p /var/lib/bspds
117cp -r /opt/bspds/frontend/dist /var/lib/bspds/frontend
118chown -R bspds:bspds /var/lib/bspds
119cat > /etc/systemd/system/bspds.service << 'EOF'
120[Unit]
121Description=BSPDS - AT Protocol PDS
122After=network.target postgresql.service minio.service
123[Service]
124Type=simple
125User=bspds
126Group=bspds
127EnvironmentFile=/etc/bspds/bspds.env
128Environment=FRONTEND_DIR=/var/lib/bspds/frontend
129ExecStart=/usr/local/bin/bspds
130Restart=always
131RestartSec=5
132[Install]
133WantedBy=multi-user.target
134EOF
135systemctl daemon-reload
136systemctl enable bspds
137systemctl start bspds
138```
139## 11. Install and Configure nginx
140Debian 13 includes nginx 1.26:
141```bash
142apt install -y nginx certbot python3-certbot-nginx
143cat > /etc/nginx/sites-available/bspds << 'EOF'
144server {
145 listen 80;
146 listen [::]:80;
147 server_name pds.example.com;
148 location / {
149 proxy_pass http://127.0.0.1:3000;
150 proxy_http_version 1.1;
151 proxy_set_header Upgrade $http_upgrade;
152 proxy_set_header Connection "upgrade";
153 proxy_set_header Host $host;
154 proxy_set_header X-Real-IP $remote_addr;
155 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
156 proxy_set_header X-Forwarded-Proto $scheme;
157 proxy_read_timeout 86400;
158 }
159}
160EOF
161ln -s /etc/nginx/sites-available/bspds /etc/nginx/sites-enabled/
162rm -f /etc/nginx/sites-enabled/default
163nginx -t
164systemctl reload nginx
165```
166## 12. Obtain Wildcard SSL Certificate
167User handles are served as subdomains (e.g., `alice.pds.example.com`), so you need a wildcard certificate.
168
169Wildcard certs require DNS-01 validation. If your DNS provider has a certbot plugin:
170```bash
171apt install -y python3-certbot-dns-cloudflare
172certbot certonly --dns-cloudflare \
173 --dns-cloudflare-credentials /etc/cloudflare.ini \
174 -d pds.example.com -d '*.pds.example.com'
175```
176
177For manual DNS validation (works with any provider):
178```bash
179certbot certonly --manual --preferred-challenges dns \
180 -d pds.example.com -d '*.pds.example.com'
181```
182Follow the prompts to add TXT records to your DNS. Note: manual mode doesn't auto-renew.
183
184After obtaining the cert, update nginx to use it and reload.
185## 13. Configure Firewall
186```bash
187apt install -y ufw
188ufw allow ssh
189ufw allow 80/tcp
190ufw allow 443/tcp
191ufw enable
192```
193## 14. Verify Installation
194```bash
195systemctl status bspds
196curl -s https://pds.example.com/xrpc/_health | jq
197curl -s https://pds.example.com/.well-known/atproto-did
198```
199## Maintenance
200View logs:
201```bash
202journalctl -u bspds -f
203```
204Update BSPDS:
205```bash
206cd /opt/bspds
207git pull
208cd frontend && deno task build && cd ..
209cargo build --release
210systemctl stop bspds
211cp target/release/bspds /usr/local/bin/
212cp -r frontend/dist /var/lib/bspds/frontend
213DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds" sqlx migrate run
214systemctl start bspds
215```
216Backup database:
217```bash
218sudo -u postgres pg_dump pds > /var/backups/pds-$(date +%Y%m%d).sql
219```