Monorepo for Tangled
docs: write upgrade guide for v1.8.x
merge all migration guides into one doc
Signed-off-by: oppiliappan <me@oppi.li>
oppiliappan
(Sep 8, 2025, 2:40 PM +0100)
febe069c
f7609e84
+51
-36
+50
docs/migrations.md
+50
docs/migrations.md
···
1
+
# Migrations
2
+
3
+
This document is laid out in reverse-chronological order.
4
+
Newer migration guides are listed first, and older guides
5
+
are further down the page.
6
+
7
+
## Upgrading from v1.8.x
8
+
9
+
After v1.8.2, the HTTP API for knots has been deprecated and
10
+
replaced with XRPC. Repositories on outdated knots will not
11
+
be viewable from the appview. Upgrading is straightforward:
12
+
13
+
- Upgrade to latest tag (v1.9.0 or above)
14
+
- Head to the [knot dashboard](https://tangled.sh/knots) and
15
+
hit the "retry" button to verify your knot
16
+
17
+
## Upgrading from v1.7.x
18
+
19
+
After v1.7.0, knot secrets have been deprecated. You no
20
+
longer need a secret from the appview to run a knot. All
21
+
authorized commands to knots are managed via [Inter-Service
22
+
Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
23
+
Knots will be read-only until upgraded.
24
+
25
+
Upgrading is quite easy, in essence:
26
+
27
+
- `KNOT_SERVER_SECRET` is no more, you can remove this
28
+
environment variable entirely
29
+
- `KNOT_SERVER_OWNER` is now required on boot, set this to
30
+
your DID. You can find your DID in the
31
+
[settings](https://tangled.sh/settings) page.
32
+
- Restart your knot once you have replaced the environment
33
+
variable
34
+
- Head to the [knot dashboard](https://tangled.sh/knots) and
35
+
hit the "retry" button to verify your knot. This simply
36
+
writes a `sh.tangled.knot` record to your PDS.
37
+
38
+
If you use the nix module, simply bump the flake to the
39
+
latest revision, and change your config block like so:
40
+
41
+
```diff
42
+
services.tangled-knot = {
43
+
enable = true;
44
+
server = {
45
+
- secretFile = /path/to/secret;
46
+
+ owner = "did:plc:foo";
47
+
};
48
+
};
49
+
```
50
+
-35
docs/migrations/knot-1.7.0.md
-35
docs/migrations/knot-1.7.0.md
···
1
-
# Upgrading from v1.7.0
2
-
3
-
After v1.7.0, knot secrets have been deprecated. You no
4
-
longer need a secret from the appview to run a knot. All
5
-
authorized commands to knots are managed via [Inter-Service
6
-
Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
7
-
Knots will be read-only until upgraded.
8
-
9
-
Upgrading is quite easy, in essence:
10
-
11
-
- `KNOT_SERVER_SECRET` is no more, you can remove this
12
-
environment variable entirely
13
-
- `KNOT_SERVER_OWNER` is now required on boot, set this to
14
-
your DID. You can find your DID in the
15
-
[settings](https://tangled.sh/settings) page.
16
-
- Restart your knot once you have replaced the environment
17
-
variable
18
-
- Head to the [knot dashboard](https://tangled.sh/knots) and
19
-
hit the "retry" button to verify your knot. This simply
20
-
writes a `sh.tangled.knot` record to your PDS.
21
-
22
-
## Nix
23
-
24
-
If you use the nix module, simply bump the flake to the
25
-
latest revision, and change your config block like so:
26
-
27
-
```diff
28
-
services.tangled-knot = {
29
-
enable = true;
30
-
server = {
31
-
- secretFile = /path/to/secret;
32
-
+ owner = "did:plc:foo";
33
-
};
34
-
};
35
-
```