ptr.pet
forked from
tranquil.farm/tranquil-pds
Our Personal Data Server from scratch!
7.0 kB
234 lines
1# Tranquil PDS production installation on NixOS
2
3This guide covers installing Tranquil PDS on NixOS via the flake and the bundled NixOS module.
4
5## Prerequisites
6
7- A server :p
8- Disk space enough for blobs (depends on usage; plan for ~1GB per active user as a baseline)
9- A domain name pointing to your server's IP
10- A wildcard TLS certificate for `*.pds.example.com` (user handles are served as subdomains)
11- Flakes enabled (`experimental-features = nix-command flakes` in `nix.conf`)
12
13## Add the flake as an input
14
15In your system flake:
16
17```nix
18{
19 inputs.tranquil.url = "git+https://tangled.org/tranquil.farm/tranquil-pds";
20
21 outputs = { self, nixpkgs, tranquil, ... }: {
22 nixosConfigurations.pds = nixpkgs.lib.nixosSystem {
23 system = "x86_64-linux";
24 modules = [
25 tranquil.nixosModules.default
26 ./configuration.nix
27 ];
28 };
29 };
30}
31```
32
33## Enable the service
34
35In `configuration.nix`:
36
37```nix
38{
39 services.tranquil-pds = {
40 enable = true;
41 database.createLocally = true; # set to false if you prefer to manually manage postgres. You must then set settings.database.url.
42 settings = {
43 server.hostname = "pds.example.com";
44 # database.url = "postgresql://user:postgres@example.com" -- Only if database.createLocally is set to false.
45 # see example.toml for all options
46 };
47 # see Secrets section for more information.
48 environmentFiles = [ "/etc/secrets/tranquil.env.production" ];
49 };
50}
51```
52
53You will also likely want to configure Caddy or nginx to actually serve traffic to the service. An example Caddy config is provided below.
54
55See [example.toml](https://tangled.org/tranquil.farm/tranquil-pds/blob/main/example.toml) at the repository root for the full set of configuration options.
56
57### Example Caddy config
58
59```nix
60{
61 services.caddy = {
62 enable = true;
63
64 virtualHosts = {
65 "pds.example.com" = {
66 # by default, tranquil runs on port 3000.
67 # You can change this with the tranquil-pds.settings.server.port option in the service config.
68 extraConfig = ''
69 reverse_proxy localhost:3000
70 '';
71 };
72 };
73 };
74
75 networking.firewall.allowedTCPPorts = [
76 80
77 443
78 ];
79}
80```
81
82### Secrets
83
84Secrets must not live in the nix store. Provide the `jwt_secret`, `dpop_secret`, and `master_key` values through `environmentFiles` instead of `settings`. example.toml documents the matching environment variable name for each. Generate each with `openssl rand -base64 48`.
85
86The simplest (least secure and least reproducible) option is to provide these secrets in a `.env` file using the `environmentFiles` option as shown above.
87
88It is recommended that you use something like [`agenix`](https://github.com/ryantm/agenix) or [`sops-nix`](https://github.com/Mic92/sops-nix) for proper secrets management on a NixOS machine instead.
89
90Example `sops-nix` config:
91
92```nix
93let
94 inherit (config.sops) secrets;
95in
96{
97 services.tranquil-pds = {
98 enable = true;
99 database.createLocally = true;
100 settings = {
101 server.hostname = "pds.example.com";
102 };
103 environmentFiles = [ secrets.tranquils-secrets.path ];
104 };
105}
106```
107
108## Communications
109
110To actually be able to receive communications from the PDS for things like verification codes, or PLC operations, you must set at least one of the following options.
111
112### Email
113
114```nix
115let
116 inherit (config.sops) secrets;
117in
118{
119 services.tranquil-pds = {
120 enable = true;
121 database.createLocally = true;
122 settings = {
123 server.hostname = "pds.example.com";
124 email.from_address = "tranquil_admin@pds.example.com";
125 # email.from_name = "Tranquil PDS";
126 };
127 environmentFiles = [ secrets.tranquils-secrets.path ];
128 };
129}
130```
131
132For DKIM options, please consult the [example.toml](https://tangled.org/tranquil.farm/tranquil-pds/blob/main/example.toml) at the repository root.
133
134### Discord
135
136```nix
137let
138 inherit (config.sops) secrets;
139in
140{
141 services.tranquil-pds = {
142 enable = true;
143 database.createLocally = true;
144 settings = {
145 server.hostname = "pds.example.com";
146 # if you're using proper secrets management, you should provide DISCORD_BOT_TOKEN in the environment file instead.
147 discord.bot_token = "whatever";
148 };
149 environmentFiles = [ secrets.tranquils-secrets.path ];
150 };
151}
152```
153
154### Telegram
155
156```nix
157let
158 inherit (config.sops) secrets;
159in
160{
161 services.tranquil-pds = {
162 enable = true;
163 database.createLocally = true;
164 settings = {
165 server.hostname = "pds.example.com";
166 telegram = {
167 # if you're using proper secrets management, you should provide TELEGRAM_BOT_TOKEN in the environment file instead.
168 bot_token = "whatever";
169 # if you're using proper secrets management, you should provide TELEGRAM_WEBHOOK_SECRET in the environment file instead.
170 webhook_secret = "whatever2";
171 };
172 };
173 environmentFiles = [ secrets.tranquils-secrets.path ];
174 };
175}
176```
177
178### Signal
179
180```nix
181let
182 inherit (config.sops) secrets;
183in
184{
185 services.tranquil-pds = {
186 enable = true;
187 database.createLocally = true;
188 settings = {
189 server.hostname = "pds.example.com";
190 # you must link a device using the admin API before enabling this option.
191 signal.enabled = true;
192 };
193 environmentFiles = [ secrets.tranquils-secrets.path ];
194 };
195}
196```
197
198### No comms channel
199
200If you have not set up any of these, you can technically still access any relevant information by querying the database directly.
201
202Please keep in mind this is a last-ditch attempt and it is highly recommended that you do in fact specify some channel for communications.
203
204Running `sudo -u tranquil-pds psql` will give you command line access to the PostgreSQL database.
205
206From there, you can run `SELECT * FROM comms_queue;` which will return all communications sent from the PDS. From there, you can extract any relevant information.
207
208## Bootstrap
209
210When the PDS service is able to properly run for the first time, you will be given a bootstrap invite code to migrate your repository to this PDS.
211
212The simplest way to find this invite code is to check the service logs by doing `journalctl -u tranquil-pds`.
213
214The log entry shold look something like this:
215
216`INFO tranquil_pds::state: No users exist and invite codes are required. Bootstrap invite code: <invite_code_here>`
217
218## Binary cache
219
220Flake artifacts, package, frontend, and devshell, are built in CI and pushed to [tranquil.cachix.org](https://tranquil.cachix.org). To pull from it instead of building locally, add to your NixOS config:
221
222```nix
223nix.settings = {
224 substituters = [ "https://tranquil.cachix.org" ];
225 trusted-public-keys = [ "tranquil.cachix.org-1:PoO+mGL6a6LcJiPakMDHN4E218/ei/7v2sxeDtNkSRg=" ];
226};
227```
228
229> [!NOTE]
230> Due to a current spindle limitation, the aarch64 package is cross-compiled on an x86_64 builder and published under a separate attribute. If you're running on aarch64, set the package manually:
231>
232> ```nix
233> services.tranquil-pds.package = inputs.tranquil.packages.x86_64-linux.tranquil-pds-aarch64;
234> ```