this repo has no description
lewis.moe
1# BSPDS Production Installation on Alpine Linux
2
3> **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.
4
5This guide covers installing BSPDS on Alpine Linux 3.23 (current stable as of December 2025).
6
7## Choose Your Installation Method
8
9| Method | Best For |
10|--------|----------|
11| **Native (this guide)** | Maximum performance, minimal footprint, full control |
12| **[Containerized](install-containers.md)** | Easier updates, isolation, reproducible deployments |
13| **[Kubernetes](install-kubernetes.md)** | Multi-node, high availability, auto-scaling |
14
15This guide covers native installation. For containerized deployment with podman and systemd quadlets, see the [container guide](install-containers.md).
16
17---
18
19## Prerequisites
20
21- A VPS with at least 2GB RAM and 20GB disk
22- A domain name pointing to your server's IP
23- Root access
24
25## 1. System Setup
26
27```sh
28apk update && apk upgrade
29apk add curl git build-base openssl-dev pkgconf
30```
31
32## 2. Install Rust
33
34```sh
35apk add rustup
36rustup-init -y
37source ~/.cargo/env
38rustup default stable
39```
40
41This installs the latest stable Rust (1.92+ as of December 2025). Alpine 3.23 also ships Rust 1.91 via `apk add rust cargo` if you prefer system packages.
42
43## 3. Install postgres
44
45Alpine 3.23 includes PostgreSQL 18:
46
47```sh
48apk add postgresql postgresql-contrib
49
50rc-update add postgresql
51/etc/init.d/postgresql setup
52rc-service postgresql start
53
54psql -U postgres -c "CREATE USER bspds WITH PASSWORD 'your-secure-password';"
55psql -U postgres -c "CREATE DATABASE pds OWNER bspds;"
56psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE pds TO bspds;"
57```
58
59## 4. Install minio
60
61```sh
62curl -O https://dl.min.io/server/minio/release/linux-amd64/minio
63chmod +x minio
64mv minio /usr/local/bin/
65
66mkdir -p /var/lib/minio/data
67adduser -D -H -s /sbin/nologin minio-user
68chown -R minio-user:minio-user /var/lib/minio
69
70cat > /etc/conf.d/minio << 'EOF'
71MINIO_ROOT_USER="minioadmin"
72MINIO_ROOT_PASSWORD="your-minio-password"
73MINIO_VOLUMES="/var/lib/minio/data"
74MINIO_OPTS="--console-address :9001"
75EOF
76
77cat > /etc/init.d/minio << 'EOF'
78#!/sbin/openrc-run
79
80name="minio"
81description="MinIO Object Storage"
82
83command="/usr/local/bin/minio"
84command_args="server ${MINIO_VOLUMES} ${MINIO_OPTS}"
85command_user="minio-user"
86command_background=true
87pidfile="/run/${RC_SVCNAME}.pid"
88output_log="/var/log/minio.log"
89error_log="/var/log/minio.log"
90
91depend() {
92 need net
93}
94
95start_pre() {
96 . /etc/conf.d/minio
97 export MINIO_ROOT_USER MINIO_ROOT_PASSWORD
98}
99EOF
100
101chmod +x /etc/init.d/minio
102rc-update add minio
103rc-service minio start
104```
105
106Create the blob bucket (wait a few seconds for minio to start):
107
108```sh
109curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
110chmod +x mc
111mv mc /usr/local/bin/
112
113mc alias set local http://localhost:9000 minioadmin your-minio-password
114mc mb local/pds-blobs
115```
116
117## 5. Install valkey
118
119Alpine 3.23 includes Valkey 9:
120
121```sh
122apk add valkey
123
124rc-update add valkey
125rc-service valkey start
126```
127
128## 6. Install deno (for frontend build)
129
130```sh
131curl -fsSL https://deno.land/install.sh | sh
132export PATH="$HOME/.deno/bin:$PATH"
133echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.profile
134```
135
136## 7. Clone and Build BSPDS
137
138```sh
139mkdir -p /opt && cd /opt
140git clone https://tangled.org/lewis.moe/bspds-sandbox bspds
141cd bspds
142
143cd frontend
144deno task build
145cd ..
146
147cargo build --release
148```
149
150## 8. Install sqlx-cli and Run Migrations
151
152```sh
153cargo install sqlx-cli --no-default-features --features postgres
154
155export DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds"
156sqlx migrate run
157```
158
159## 9. Configure BSPDS
160
161```sh
162mkdir -p /etc/bspds
163cp /opt/bspds/.env.example /etc/bspds/bspds.env
164chmod 600 /etc/bspds/bspds.env
165```
166
167Edit `/etc/bspds/bspds.env` and fill in your values. Generate secrets with:
168
169```sh
170openssl rand -base64 48
171```
172
173## 10. Create OpenRC Service
174
175```sh
176adduser -D -H -s /sbin/nologin bspds
177
178cp /opt/bspds/target/release/bspds /usr/local/bin/
179mkdir -p /var/lib/bspds
180cp -r /opt/bspds/frontend/dist /var/lib/bspds/frontend
181chown -R bspds:bspds /var/lib/bspds
182
183cat > /etc/init.d/bspds << 'EOF'
184#!/sbin/openrc-run
185
186name="bspds"
187description="BSPDS - AT Protocol PDS"
188
189command="/usr/local/bin/bspds"
190command_user="bspds"
191command_background=true
192pidfile="/run/${RC_SVCNAME}.pid"
193output_log="/var/log/bspds.log"
194error_log="/var/log/bspds.log"
195
196depend() {
197 need net postgresql minio
198}
199
200start_pre() {
201 export FRONTEND_DIR=/var/lib/bspds/frontend
202 . /etc/bspds/bspds.env
203 export SERVER_HOST SERVER_PORT PDS_HOSTNAME DATABASE_URL
204 export S3_ENDPOINT AWS_REGION S3_BUCKET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
205 export VALKEY_URL JWT_SECRET DPOP_SECRET MASTER_KEY APPVIEW_URL CRAWLERS
206}
207EOF
208
209chmod +x /etc/init.d/bspds
210rc-update add bspds
211rc-service bspds start
212```
213
214## 11. Install and Configure nginx
215
216Alpine 3.23 includes nginx 1.28:
217
218```sh
219apk add nginx certbot certbot-nginx
220
221cat > /etc/nginx/http.d/bspds.conf << 'EOF'
222server {
223 listen 80;
224 listen [::]:80;
225 server_name pds.example.com;
226
227 location / {
228 proxy_pass http://127.0.0.1:3000;
229 proxy_http_version 1.1;
230 proxy_set_header Upgrade $http_upgrade;
231 proxy_set_header Connection "upgrade";
232 proxy_set_header Host $host;
233 proxy_set_header X-Real-IP $remote_addr;
234 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
235 proxy_set_header X-Forwarded-Proto $scheme;
236 proxy_read_timeout 86400;
237 }
238}
239EOF
240
241rc-update add nginx
242rc-service nginx start
243```
244
245## 12. Obtain SSL Certificate
246
247```sh
248certbot --nginx -d pds.example.com
249```
250
251Set up auto-renewal:
252
253```sh
254echo "0 0 * * * certbot renew --quiet" | crontab -
255```
256
257## 13. Configure Firewall
258
259```sh
260apk add iptables ip6tables
261
262iptables -A INPUT -p tcp --dport 22 -j ACCEPT
263iptables -A INPUT -p tcp --dport 80 -j ACCEPT
264iptables -A INPUT -p tcp --dport 443 -j ACCEPT
265iptables -A INPUT -i lo -j ACCEPT
266iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
267iptables -P INPUT DROP
268
269ip6tables -A INPUT -p tcp --dport 22 -j ACCEPT
270ip6tables -A INPUT -p tcp --dport 80 -j ACCEPT
271ip6tables -A INPUT -p tcp --dport 443 -j ACCEPT
272ip6tables -A INPUT -i lo -j ACCEPT
273ip6tables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
274ip6tables -P INPUT DROP
275
276rc-update add iptables
277rc-update add ip6tables
278/etc/init.d/iptables save
279/etc/init.d/ip6tables save
280```
281
282## 14. Verify Installation
283
284```sh
285rc-service bspds status
286curl -s https://pds.example.com/xrpc/_health
287curl -s https://pds.example.com/.well-known/atproto-did
288```
289
290## Maintenance
291
292View logs:
293```sh
294tail -f /var/log/bspds.log
295```
296
297Update BSPDS:
298```sh
299cd /opt/bspds
300git pull
301cd frontend && deno task build && cd ..
302cargo build --release
303rc-service bspds stop
304cp target/release/bspds /usr/local/bin/
305cp -r frontend/dist /var/lib/bspds/frontend
306DATABASE_URL="postgres://bspds:your-secure-password@localhost:5432/pds" sqlx migrate run
307rc-service bspds start
308```
309
310Backup database:
311```sh
312pg_dump -U postgres pds > /var/backups/pds-$(date +%Y%m%d).sql
313```