Skip to content

Commit 37f4702

Browse files
jmattheisjmattheis
committed
fix: migration docs
1 parent e86b6fd commit 37f4702

3 files changed

Lines changed: 160 additions & 1 deletion

File tree

‎.vitepress/config.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,10 @@ export default defineConfig({
4242
items: [
4343
{text: 'Intro to Gotify Plugins', link: '/docs/plugin'},
4444
{text: 'Writing Plugins', link: '/docs/plugin-write'},
45-
{text: 'Building and Deploying Plugins', link: '/docs/plugin-deploy'},
45+
{
46+
text: 'Building and Deploying Plugins',
47+
link: '/docs/plugin-deploy',
48+
},
4649
],
4750
},
4851
{
@@ -57,6 +60,8 @@ export default defineConfig({
5760
text: 'Guides',
5861
items: [
5962
{text: 'OpenID Connect (OIDC)', link: '/docs/oidc'},
63+
{text: 'Session Elevation', link: '/docs/session-elevation'},
64+
{text: 'Migrate to 3.x', link: '/docs/migrate-to-3'},
6065
{text: 'Apache reverse proxy', link: '/docs/apache'},
6166
{text: 'Caddy 2 reverse proxy', link: '/docs/caddy'},
6267
{text: 'Haproxy reverse proxy', link: '/docs/haproxy'},

‎docs/migrate-to-3.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Migrate to 3.x
2+
3+
- The `config.yml` file is no longer supported, convert it to the new env format
4+
with [`migrate-config`](#migrating-your-config).
5+
- If you set list or map environment variables, their syntax changed, see
6+
[List and map syntax](#list-and-map-syntax).
7+
- If you have scripts hitting client-token endpoints, they may now need
8+
[elevation](#adapting-your-scripts).
9+
10+
## Config Changes
11+
12+
### YAML config file removed
13+
14+
The YAML config file (`config.yml`) is no longer supported. Gotify can now be
15+
only configured by environment variables, which can be loaded from an env file.
16+
The first existing file from this search order is loaded:
17+
18+
1. `gotify-server.env` (in the working directory)
19+
2. `$XDG_CONFIG_HOME/gotify/gotify-server.env` (`$XDG_CONFIG_HOME` falls back to `$HOME/.config` when unset)
20+
3. `/etc/gotify/server.env`
21+
22+
See the [Configuration](/docs/config) page for the full list of variables.
23+
24+
### Migrating your config
25+
26+
The `migrate-config` command converts an existing `config.yml` to the new env
27+
format. It prints the result to stdout.
28+
29+
```bash
30+
$ gotify-server migrate-config config.yml > gotify-server.env
31+
```
32+
33+
With Docker:
34+
35+
```bash
36+
$ docker run --rm -v "$(pwd)/config.yml:/app/config.yml" gotify/server \
37+
migrate-config config.yml > gotify-server.env
38+
```
39+
40+
### Environment List and map syntax
41+
42+
Defining settings via environment variables was already possible, but the syntax
43+
for list and map values has changed. If you set any of the variables below, update
44+
their format.
45+
46+
**Lists** are now comma-separated instead of a YAML array:
47+
48+
- `GOTIFY_SERVER_TRUSTEDPROXIES`
49+
- `GOTIFY_SERVER_CORS_ALLOWORIGINS`
50+
- `GOTIFY_SERVER_CORS_ALLOWMETHODS`
51+
- `GOTIFY_SERVER_CORS_ALLOWHEADERS`
52+
- `GOTIFY_SERVER_STREAM_ALLOWEDORIGINS`
53+
- `GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS`
54+
- `GOTIFY_OIDC_SCOPES`
55+
56+
```bash
57+
# before
58+
GOTIFY_SERVER_TRUSTEDPROXIES=[127.0.0.1/32, ::1]
59+
# after
60+
GOTIFY_SERVER_TRUSTEDPROXIES=127.0.0.1/32,::1
61+
```
62+
63+
**Maps** are now a JSON object instead of a YAML map:
64+
65+
- `GOTIFY_SERVER_RESPONSEHEADERS`
66+
67+
```bash
68+
# before
69+
GOTIFY_SERVER_RESPONSEHEADERS={X-Custom-Header: "custom value"}
70+
# after
71+
GOTIFY_SERVER_RESPONSEHEADERS={"X-Custom-Header":"custom value"}
72+
```
73+
74+
## API Changes
75+
76+
Introduces step-up authentication via time-limited [session
77+
elevation](./session-elevation.md). A session/client token must re-authenticate
78+
before sensitive, hard-to-undo actions.
79+
80+
HTTP Basic auth and application tokens are unaffected.
81+
82+
### Endpoints that now require elevation
83+
84+
With a non-elevated client token these return `403`:
85+
86+
| Endpoint | Action |
87+
| :-------------------------------------------- | :----------------------------- |
88+
| `POST /current/user/password` | Change current user's password |
89+
| `DELETE /client/{id}` | Delete a client |
90+
| `DELETE /application/{id}` | Delete an application |
91+
| `POST /client/{id}/elevate` | Elevate a client token |
92+
| `GET /user`, `GET`/`POST`/`DELETE /user/{id}` | Manage users (admin) |
93+
94+
The `Client` and `CurrentUser` models have gotten elevation-related fields. See the
95+
[API documentation](/api-docs) for details.
96+
97+
### Adapting your scripts
98+
99+
Scripts that hit the endpoints above with a client token now need that token to
100+
be elevated. Either:
101+
102+
- Use HTTP Basic auth as they are elevated by default.
103+
- Elevate the client in the WebUI or the api with basic auth.
104+
105+
## CLI Changes
106+
107+
The binary now uses subcommands. You should migrate to using the `serve`
108+
subcommand. For backwards compatibility running gotify without a command will
109+
continue to serve the server.
110+
111+
```bash
112+
$ ./gotify-linux-amd64 serve
113+
```
114+
115+
The Docker image already defaults to `serve`, so `docker run` and Docker Compose
116+
setups keep working unchanged.

‎docs/session-elevation.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Session Elevation
2+
3+
[[toc]]
4+
5+
Session elevation requires you to re-authenticate before performing sensitive,
6+
hard-to-undo actions, even while already logged in.
7+
8+
## What requires elevation
9+
10+
These actions need an **elevated** session; with a plain client token they
11+
return `403 Forbidden`:
12+
13+
| Action | Endpoint |
14+
| :----------------------------- | :-------------------------------------------- |
15+
| Change current user's password | `POST /current/user/password` |
16+
| Delete a client | `DELETE /client/{id}` |
17+
| Delete an application | `DELETE /application/{id}` |
18+
| Elevate a session | `POST /client/{id}/elevate` |
19+
| Manage users (admin) | `GET /user`, `GET`/`POST`/`DELETE /user/{id}` |
20+
21+
## How to elevate
22+
23+
### In the WebUI
24+
25+
When you trigger a protected action, the UI prompts you to re-authenticate and
26+
then performs the action.
27+
28+
### Via the API
29+
30+
If you use a client token in a script, you have two options.
31+
32+
1. basic-auth requests are always elevated (see below), so you can call the protected endpoint directly with username and password:
33+
34+
```bash
35+
curl -u "user:password" -X DELETE "https://gotify.example.com/client/7"
36+
```
37+
38+
2. If you must authenticate with the token itself, elevate its session first. This can be done via the API or the WebUI.

0 commit comments

Comments
 (0)