website/docs: sys mgmt: document authentik backups/restoration

[dominic-r]

What?

This PR adds general documentation to backup authentik: the postgres database, the redis instance, and static directories.

Closes

Closes #8411

• The documentation has been updated
• The documentation has been formatted (make website)

[netlify]

✅ Deploy Preview for authentik-docs ready!

Name	Link
🔨 Latest commit	db4d2df
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-docs/deploys/67b37ca7b4576400088237c6
😎 Deploy Preview	https://deploy-preview-12943--authentik-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ Deploy Preview for authentik-storybook canceled.

Name	Link
🔨 Latest commit	db4d2df
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-storybook/deploys/67b37ca72dc6af0008ae3c03

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.74%. Comparing base (e9c944c) to head (db4d2df).
Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #12943      +/-   ##
==========================================
- Coverage   92.76%   92.74%   -0.02%     
==========================================
  Files         785      792       +7     
  Lines       39636    40218     +582     
==========================================
+ Hits        36768    37301     +533     
- Misses       2868     2917      +49     

Flag	Coverage Δ
e2e	48.11% <ø> (-0.43%)	⬇️
integration	24.48% <ø> (-0.06%)	⬇️
unit	90.51% <ø> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dominic-r]

Depends on #12962 for the Docker container names.

[rissson]

Depends on #12962 for the Docker container names.

You don't need to, we assume in the documentation that a bunch of commands are run from the docker-compose directory.

[rissson]

One thing I forgot to mention, I don't want us to provide specific instructions for backing things up, but instead provide references to our dependencies respective documentation.

[dominic-r]

One thing I forgot to mention, I don't want us to provide specific instructions for backing things up, but instead provide references to our dependencies respective documentation.

For example, linking the Postgres backup page instead of providing a command? I'm curious, is there any specific reasoning behind this? While this might simplify things for us, it could ultimately create more challenges for the user, particularly those who aren’t as familiar with Postgres or Redis. There’s a risk they could end up relying on commands from unreliable third-party documentation or their own improvised solutions, which could lead to data loss or improper backups due to incorrect usage or poor practices. Wouldn’t it be safer and more effective to direct them to the official dependency documentation and provide commands?

[dominic-r]

This is a bit like one of my first PRs to authentik: upgrading PG from v12 to 16. We could have linked pg_restore/pg_dump/pg_whateverelse docs but instead we provided a step-by-step with postgres commands.

[rissson]

For example, linking the Postgres backup page instead of providing a command?

Exactly

I'm curious, is there any specific reasoning behind this?

There is.

First, there is the added maintenance for us. Providing specific instructions would mean that we have to maintain those, possibly for multiple versions of postgres (for instance the helm chart and the docker-compose ones don't currently match). It also means that we would need to provide some level of support for issues and questions coming in. We currently don't have that kind of bandwidth.

Backing things up (whether it's postgres, redis, files, or whatever else) is never easy and straightforward. Providing commands would make it look like it is, but it isn't. There are many other things to consider, like the fact that we also need to backup users and their password so that on restore.

While on the topic of restoration, we would also need to provide additional instructions for that.

We also need to consider that using the provided postgres/redis setup with the docker-compose and helm chart is not the way everyone runs authentik.

I would much rather have explanations of what needs to be backed up, why it needs to be backed up, and solid pointers to resources explaining how to do it, instead of us trying to "make things up" even though it isn't our expertise.

There’s a risk they could end up relying on commands from unreliable third-party documentation or their own improvised solutions

Not our problem. Seriously. I know it sounds harsh, but if anyone is running an application (authentik or else) and rely on that data without having 1. learned how to do backups and 2. proper setup and testing of said backups, they shouldn't be running that application.

Which is why I want us to point people in the right direction, with links to references of the upstream backup documentation for example.

[dominic-r]

sorry for taking a while to get to this. I've implemented your suggestions in e3292ee . Hope I wasn't too specific or vague on certain points. Restoration docs is also added in b92ab8d

If you choose to keep "Restore Notes" (under "Static directories"), wording will probably have to be updated. I'm not proud of my descriptions.

[rissson]

Overall a pretty good document. I very much like the way things are laid out and organized

[rissson]

was out sick some time this week, I'll get to this next week