Our Personal Data Server from scratch!
docs: start a contributing file to track how to work with the repo
Signed-off-by: Trezy <tre@trezy.com>
+119
+119
CONTRIBUTING.md
+119
CONTRIBUTING.md
···
1
+
# Contributing to Tranquil PDS
2
+
3
+
## Local Development
4
+
5
+
### Prerequisites
6
+
7
+
- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
8
+
- Add `pds.test` to your hosts file (one-time setup):
9
+
10
+
```
11
+
127.0.0.1 pds.test
12
+
```
13
+
14
+
- **macOS / Linux:** `/etc/hosts`
15
+
- **Windows:** `C:\Windows\System32\drivers\etc\hosts`
16
+
17
+
### Starting the dev environment
18
+
19
+
```bash
20
+
just run-dev
21
+
```
22
+
23
+
This starts the following services via `docker-compose`:
24
+
25
+
- **Traefik** — HTTPS reverse proxy at `https://pds.test`
26
+
- **Backend** — Rust server with `cargo-watch` (auto-rebuilds on file changes)
27
+
- **Frontend** — Vite dev server with hot module replacement
28
+
- **Postgres** — Database on port 5432
29
+
- **PLC Directory** — Local [did-method-plc](https://github.com/did-method-plc/did-method-plc) server for DID registration
30
+
- **Mailpit** — Local email server with web UI at [http://localhost:8025](http://localhost:8025)
31
+
32
+
Once all services are running, open **https://pds.test** in your browser.
33
+
34
+
### Trusting the self-signed certificate
35
+
36
+
Traefik generates a self-signed TLS certificate. Your browser will show a security warning on first visit. You can either click through it, or add the certificate to your system trust store for a seamless experience:
37
+
38
+
**macOS:**
39
+
40
+
```bash
41
+
# Extract the cert from traefik and add it to the system keychain
42
+
echo | openssl s_client -connect localhost:443 -servername pds.test 2>/dev/null | openssl x509 > /tmp/pds-test.pem
43
+
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/pds-test.pem
44
+
```
45
+
46
+
**Linux (Debian/Ubuntu):**
47
+
48
+
```bash
49
+
echo | openssl s_client -connect localhost:443 -servername pds.test 2>/dev/null | openssl x509 | sudo tee /usr/local/share/ca-certificates/pds-test.crt
50
+
sudo update-ca-certificates
51
+
```
52
+
53
+
**Linux (Fedora/RHEL):**
54
+
55
+
```bash
56
+
echo | openssl s_client -connect localhost:443 -servername pds.test 2>/dev/null | openssl x509 | sudo tee /etc/pki/ca-trust/source/anchors/pds-test.pem
57
+
sudo update-ca-trust
58
+
```
59
+
60
+
**Windows (PowerShell as Administrator):**
61
+
62
+
```powershell
63
+
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
64
+
$cert.Import([System.Text.Encoding]::UTF8.GetBytes((echo | openssl s_client -connect localhost:443 -servername pds.test 2>$null | openssl x509)))
65
+
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store("Root", "LocalMachine")
66
+
$store.Open("ReadWrite")
67
+
$store.Add($cert)
68
+
$store.Close()
69
+
```
70
+
71
+
Restart your browser after adding the certificate.
72
+
73
+
### Stopping the dev environment
74
+
75
+
```bash
76
+
# Stop containers (preserves database + build cache)
77
+
docker compose --profile dev down
78
+
79
+
# Stop and wipe all data (fresh start)
80
+
docker compose --profile dev down -v
81
+
```
82
+
83
+
### Direct database access
84
+
85
+
Postgres is exposed on port 5432:
86
+
87
+
```bash
88
+
psql postgres://postgres:postgres@localhost:5432/pds
89
+
```
90
+
91
+
### How it works
92
+
93
+
- **Source code** is bind-mounted into the containers so that changes made on the host will be immediately reflected in the application
94
+
- **Backend** uses `cargo-watch` to recompile and restart when Rust files change
95
+
- **Frontend** uses Vite's HMR for instant browser updates when frontend files change
96
+
- **Build cache** (`target/` directory and cargo registry) are stored in Docker volumes, so incremental compilation persists across container restarts
97
+
- **Traefik** routes `/`, `/xrpc`, `/oauth`, `/.well-known`, `/u`, and `/health` to the backend; everything else goes to the Vite dev server
98
+
- **Mailpit** captures all outgoing email — open [http://localhost:8025](http://localhost:8025) to view verification emails during registration
99
+
- **PLC Directory** runs locally so DID registration doesn't hit the real `plc.directory`
100
+
101
+
### Running the backend natively
102
+
103
+
If you prefer running the Rust backend outside Docker (faster incremental builds on host), you need:
104
+
105
+
- Rust toolchain (see `rust-toolchain.toml`)
106
+
- `protoc` (`brew install protobuf` on macOS)
107
+
- PostgreSQL (start with `docker compose up db`)
108
+
109
+
Then run:
110
+
111
+
```bash
112
+
cargo run -p tranquil-server -- --config config.toml
113
+
```
114
+
115
+
And start the frontend separately:
116
+
117
+
```bash
118
+
cd frontend && pnpm install && pnpm dev
119
+
```