wrote up more stuff for deploying on nixos systems
+174
-3
Diff
round #0
+174
-3
docs/install-nix.md
+174
-3
docs/install-nix.md
···
38
38
{
39
39
services.tranquil-pds = {
40
40
enable = true;
41
-
database.createLocally = true;
41
+
database.createLocally = true; # set to false if you prefer to manually manage postgres. You must then set settings.database.url.
42
42
settings = {
43
43
server.hostname = "pds.example.com";
44
+
# database.url = "postgresql://user:postgres@example.com" -- Only if database.createLocally is set to false.
44
45
# see example.toml for all options
45
46
};
47
+
# see Secrets section for more information.
48
+
environmentFiles = [ "/etc/secrets/tranquil.env.production" ];
49
+
};
50
+
}
51
+
```
52
+
53
+
You will also likely want to configure Caddy or nginx to actually serve traffic to the service. An example Caddy config is provided below.
54
+
55
+
See [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
+
84
+
Additionally, you will need to provide the following environment variables.
85
+
86
+
```env
87
+
# use `openssl rand -base64 32` to generate these.
88
+
JWT_SECRET=<secret_here>
89
+
DPOP_SECRET=<secret_here>
90
+
MASTER_KEY=<secret_here>
91
+
```
92
+
93
+
The simplest (least secure and least reproducible) option is to provide these secrets in a `.env` file using the `environmentFiles` option as shown above.
94
+
95
+
It 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.
96
+
97
+
Example `sops-nix` config:
98
+
99
+
```nix
100
+
let
101
+
inherit (config.sops) secrets;
102
+
in
103
+
{
104
+
services.tranquil-pds = {
105
+
enable = true;
106
+
database.createLocally = true;
107
+
settings = {
108
+
server.hostname = "pds.example.com";
109
+
};
110
+
environmentFiles = [ secrets.tranquils-secrets.path ];
111
+
};
112
+
}
113
+
```
114
+
115
+
## Communications
116
+
117
+
To 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.
118
+
119
+
### Email
120
+
121
+
```nix
122
+
let
123
+
inherit (config.sops) secrets;
124
+
in
125
+
{
126
+
services.tranquil-pds = {
127
+
enable = true;
128
+
database.createLocally = true;
129
+
settings = {
130
+
server.hostname = "pds.example.com";
131
+
email.from_address = "tranquil_admin@pds.example.com";
132
+
# email.from_name = "Tranquil PDS";
133
+
};
134
+
environmentFiles = [ secrets.tranquils-secrets.path ];
46
135
};
47
136
}
48
137
```
49
138
50
-
This will set up the local postgres database for you automatically. If you prefer to manage postgres yourself, leave `database.createLocally` at its default (`false`) and set `settings.database.url` manually.
139
+
For DKIM options, please consult the [example.toml](https://tangled.org/tranquil.farm/tranquil-pds/blob/main/example.toml) at the repository root.
140
+
141
+
### Discord
142
+
143
+
```nix
144
+
let
145
+
inherit (config.sops) secrets;
146
+
in
147
+
{
148
+
services.tranquil-pds = {
149
+
enable = true;
150
+
database.createLocally = true;
151
+
settings = {
152
+
server.hostname = "pds.example.com";
153
+
# if you're using proper secrets management, you should provide DISCORD_BOT_TOKEN in the environment file instead.
154
+
discord.bot_token = "whatever";
155
+
};
156
+
environmentFiles = [ secrets.tranquils-secrets.path ];
157
+
};
158
+
}
159
+
```
160
+
161
+
### Telegram
162
+
163
+
```nix
164
+
let
165
+
inherit (config.sops) secrets;
166
+
in
167
+
{
168
+
services.tranquil-pds = {
169
+
enable = true;
170
+
database.createLocally = true;
171
+
settings = {
172
+
server.hostname = "pds.example.com";
173
+
telegram = {
174
+
# if you're using proper secrets management, you should provide TELEGRAM_BOT_TOKEN in the environment file instead.
175
+
bot_token = "whatever";
176
+
# if you're using proper secrets management, you should provide TELEGRAM_WEBHOOK_SECRET in the environment file instead.
177
+
webhook_secret = "whatever2";
178
+
};
179
+
};
180
+
environmentFiles = [ secrets.tranquils-secrets.path ];
181
+
};
182
+
}
183
+
```
184
+
185
+
### Signal
186
+
187
+
```nix
188
+
let
189
+
inherit (config.sops) secrets;
190
+
in
191
+
{
192
+
services.tranquil-pds = {
193
+
enable = true;
194
+
database.createLocally = true;
195
+
settings = {
196
+
server.hostname = "pds.example.com";
197
+
# you must link a device using the admin API before enabling this option.
198
+
signal.enabled = true;
199
+
};
200
+
environmentFiles = [ secrets.tranquils-secrets.path ];
201
+
};
202
+
}
203
+
```
204
+
205
+
### No comms channel
206
+
207
+
If you have not set up any of these, you can technically still access any relevant information by querying the database directly.
208
+
209
+
Please keep in mind this is a last-ditch attempt and it is highly recommended that you do in fact specify some channel for communications.
210
+
211
+
Running `sudo -u tranquil-pds psql` will give you command line access to the PostgreSQL database.
212
+
213
+
From 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.
214
+
215
+
## Bootstrap
216
+
217
+
When 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.
218
+
219
+
The simplest way to find this invite code is to check the service logs by doing `journalctl -u tranquil-pds`.
220
+
221
+
The log entry shold look something like this:
51
222
52
-
See [example.toml](../example.toml) for the full set of configuration options.
223
+
`INFO tranquil_pds::state: No users exist and invite codes are required. Bootstrap invite code: <invite_code_here>`
53
224
54
225
## Binary cache
55
226
History
1 round
0 comments
did:plc:fnvdhaoe7b5abgrtvzf4ttl5
submitted
#0
1 commit
expand
collapse
feat(docs): clarify nix documentation
merge conflicts detected
expand
collapse
expand
collapse