this repo has no description
lewis.moe
1# Tranquil PDS Production Installation on Alpine Linux
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 Tranquil PDS on Alpine Linux 3.23.
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 access
11## 1. System Setup
12```sh
13apk update && apk upgrade
14apk add curl git build-base openssl-dev pkgconf
15```
16## 2. Install Rust
17```sh
18apk add rustup
19rustup-init -y
20source ~/.cargo/env
21rustup default stable
22```
23This installs the latest stable Rust. Alpine also ships Rust via `apk add rust cargo` if you prefer system packages.
24## 3. Install postgres
25```sh
26apk add postgresql postgresql-contrib
27rc-update add postgresql
28/etc/init.d/postgresql setup
29rc-service postgresql start
30psql -U postgres -c "CREATE USER tranquil_pds WITH PASSWORD 'your-secure-password';"
31psql -U postgres -c "CREATE DATABASE pds OWNER tranquil_pds;"
32psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE pds TO tranquil_pds;"
33```
34## 4. Install minio
35```sh
36curl -O https://dl.min.io/server/minio/release/linux-amd64/minio
37chmod +x minio
38mv minio /usr/local/bin/
39mkdir -p /var/lib/minio/data
40adduser -D -H -s /sbin/nologin minio-user
41chown -R minio-user:minio-user /var/lib/minio
42cat > /etc/conf.d/minio << 'EOF'
43MINIO_ROOT_USER="minioadmin"
44MINIO_ROOT_PASSWORD="your-minio-password"
45MINIO_VOLUMES="/var/lib/minio/data"
46MINIO_OPTS="--console-address :9001"
47EOF
48cat > /etc/init.d/minio << 'EOF'
49#!/sbin/openrc-run
50name="minio"
51description="MinIO Object Storage"
52command="/usr/local/bin/minio"
53command_args="server ${MINIO_VOLUMES} ${MINIO_OPTS}"
54command_user="minio-user"
55command_background=true
56pidfile="/run/${RC_SVCNAME}.pid"
57output_log="/var/log/minio.log"
58error_log="/var/log/minio.log"
59depend() {
60 need net
61}
62start_pre() {
63 . /etc/conf.d/minio
64 export MINIO_ROOT_USER MINIO_ROOT_PASSWORD
65}
66EOF
67chmod +x /etc/init.d/minio
68rc-update add minio
69rc-service minio start
70```
71Create the blob bucket (wait a few seconds for minio to start):
72```sh
73curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
74chmod +x mc
75mv mc /usr/local/bin/
76mc alias set local http://localhost:9000 minioadmin your-minio-password
77mc mb local/pds-blobs
78```
79## 5. Install valkey
80```sh
81apk add valkey
82rc-update add valkey
83rc-service valkey start
84```
85## 6. Install deno (for frontend build)
86```sh
87curl -fsSL https://deno.land/install.sh | sh
88export PATH="$HOME/.deno/bin:$PATH"
89echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.profile
90```
91## 7. Clone and Build Tranquil PDS
92```sh
93mkdir -p /opt && cd /opt
94git clone https://tangled.org/lewis.moe/bspds-sandbox tranquil-pds
95cd tranquil-pds
96cd frontend
97deno task build
98cd ..
99cargo build --release
100```
101## 8. Install sqlx-cli and Run Migrations
102```sh
103cargo install sqlx-cli --no-default-features --features postgres
104export DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds"
105sqlx migrate run
106```
107## 9. Configure Tranquil PDS
108```sh
109mkdir -p /etc/tranquil-pds
110cp /opt/tranquil-pds/.env.example /etc/tranquil-pds/tranquil-pds.env
111chmod 600 /etc/tranquil-pds/tranquil-pds.env
112```
113Edit `/etc/tranquil-pds/tranquil-pds.env` and fill in your values. Generate secrets with:
114```sh
115openssl rand -base64 48
116```
117## 10. Create OpenRC Service
118```sh
119adduser -D -H -s /sbin/nologin tranquil-pds
120cp /opt/tranquil-pds/target/release/tranquil-pds /usr/local/bin/
121mkdir -p /var/lib/tranquil-pds
122cp -r /opt/tranquil-pds/frontend/dist /var/lib/tranquil-pds/frontend
123chown -R tranquil-pds:tranquil-pds /var/lib/tranquil-pds
124cat > /etc/init.d/tranquil-pds << 'EOF'
125#!/sbin/openrc-run
126name="tranquil-pds"
127description="Tranquil PDS - AT Protocol PDS"
128command="/usr/local/bin/tranquil-pds"
129command_user="tranquil-pds"
130command_background=true
131pidfile="/run/${RC_SVCNAME}.pid"
132output_log="/var/log/tranquil-pds.log"
133error_log="/var/log/tranquil-pds.log"
134depend() {
135 need net postgresql minio
136}
137start_pre() {
138 export FRONTEND_DIR=/var/lib/tranquil-pds/frontend
139 . /etc/tranquil-pds/tranquil-pds.env
140 export SERVER_HOST SERVER_PORT PDS_HOSTNAME DATABASE_URL
141 export S3_ENDPOINT AWS_REGION S3_BUCKET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
142 export VALKEY_URL JWT_SECRET DPOP_SECRET MASTER_KEY CRAWLERS
143}
144EOF
145chmod +x /etc/init.d/tranquil-pds
146rc-update add tranquil-pds
147rc-service tranquil-pds start
148```
149## 11. Install and Configure nginx
150```sh
151apk add nginx certbot certbot-nginx
152cat > /etc/nginx/http.d/tranquil-pds.conf << 'EOF'
153server {
154 listen 80;
155 listen [::]:80;
156 server_name pds.example.com;
157 location / {
158 proxy_pass http://127.0.0.1:3000;
159 proxy_http_version 1.1;
160 proxy_set_header Upgrade $http_upgrade;
161 proxy_set_header Connection "upgrade";
162 proxy_set_header Host $host;
163 proxy_set_header X-Real-IP $remote_addr;
164 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
165 proxy_set_header X-Forwarded-Proto $scheme;
166 proxy_read_timeout 86400;
167 }
168}
169EOF
170rc-update add nginx
171rc-service nginx start
172```
173## 12. Obtain Wildcard SSL Certificate
174User handles are served as subdomains (e.g., `alice.pds.example.com`), so you need a wildcard certificate.
175
176Wildcard certs require DNS-01 validation. For manual DNS validation (works with any provider):
177```sh
178certbot certonly --manual --preferred-challenges dns \
179 -d pds.example.com -d '*.pds.example.com'
180```
181Follow the prompts to add TXT records to your DNS.
182
183If your DNS provider has a certbot plugin, you can use that for auto-renewal:
184```sh
185apk add certbot-dns-cloudflare
186certbot certonly --dns-cloudflare \
187 --dns-cloudflare-credentials /etc/cloudflare.ini \
188 -d pds.example.com -d '*.pds.example.com'
189```
190
191After obtaining the cert, update nginx to use it, then set up auto-renewal:
192```sh
193echo "0 0 * * * certbot renew --quiet && rc-service nginx reload" | crontab -
194```
195## 13. Configure Firewall
196```sh
197apk add iptables ip6tables
198iptables -A INPUT -p tcp --dport 22 -j ACCEPT
199iptables -A INPUT -p tcp --dport 80 -j ACCEPT
200iptables -A INPUT -p tcp --dport 443 -j ACCEPT
201iptables -A INPUT -i lo -j ACCEPT
202iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
203iptables -P INPUT DROP
204ip6tables -A INPUT -p tcp --dport 22 -j ACCEPT
205ip6tables -A INPUT -p tcp --dport 80 -j ACCEPT
206ip6tables -A INPUT -p tcp --dport 443 -j ACCEPT
207ip6tables -A INPUT -i lo -j ACCEPT
208ip6tables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
209ip6tables -P INPUT DROP
210rc-update add iptables
211rc-update add ip6tables
212/etc/init.d/iptables save
213/etc/init.d/ip6tables save
214```
215## 14. Verify Installation
216```sh
217rc-service tranquil-pds status
218curl -s https://pds.example.com/xrpc/_health
219curl -s https://pds.example.com/.well-known/atproto-did
220```
221## Maintenance
222View logs:
223```sh
224tail -f /var/log/tranquil-pds.log
225```
226Update Tranquil PDS:
227```sh
228cd /opt/tranquil-pds
229git pull
230cd frontend && deno task build && cd ..
231cargo build --release
232rc-service tranquil-pds stop
233cp target/release/tranquil-pds /usr/local/bin/
234cp -r frontend/dist /var/lib/tranquil-pds/frontend
235DATABASE_URL="postgres://tranquil_pds:your-secure-password@localhost:5432/pds" sqlx migrate run
236rc-service tranquil-pds start
237```
238Backup database:
239```sh
240pg_dump -U postgres pds > /var/backups/pds-$(date +%Y%m%d).sql
241```