doc: added server documentation template

This commit is contained in:
missytake 2024-12-04 14:44:20 +01:00
parent cf7850ecde
commit 6f8c765f00
Signed by: missytake
GPG key ID: 04CC6658320518DF

104
TEMPLATE.md Normal file
View file

@ -0,0 +1,104 @@
# Server: Server name
## Usage
Who is using this server?
Who needs the server and will be affected if the server is not working?
## Maintainers
Who to ask about this server?
## Domain Settings
Where are the DNS settings? E.g. with Hetzner or in a DNS zone file.
How to change DNS settings?
Which domains and subdomains exist?
## Hosting
Where is the server hosted?
Add a link to the hosting admin interface, e.g. <https://console.hetzner.cloud/>.
## Services
Which services are running there?
E.g. there are a `www.example.org` and `ci.example.org` services.
### Service: ci.example.org
Each service has a greppable heading starting with `### Service: `.
Which software the service is running? E.g. nginx.
How was it deployed? E.g. manually or with pyinfra.
How can the software be managed,
Where the admin credentials are stored if you need to fix something (e.g. for mailcow)?
Is there an admin chatgroup (e.g. for mailadm) and how to join it?
#### Monitoring
How to read the logs of the service?
How admins are notified when the service is down?
#### Deployment
How the service was deployed?
How to reinstall it?
#### Upgrade Strategy
How the service is upgraded?
Which commands to run to upgrade it, e.g. where the upgrade script is located and how to run it?
If there is an official documentation, put a link to it in this section.
#### Maintainers
Who to ask about the service?
#### Integration
How the service is related to other services running on this or other servers?
E.g. service `ci.example.org` uses the secret storage `secrets.example.net` and runner `runner.example.com` hosted elsewhere.
### Service: www.example.org
Description similar to the other service.
## Users
Who has access to this server?
Which admin accounts are there?
Which service accounts are there?
Which user accounts are there?
## Monitoring
How do we notice if something fails?
Where do the errors show up?
Where the logs for the services are located, e.g. Postfix logs go to `/var/log/mail.log`.
## Upgrade Strategy
How do we keep the services up to date?
## Backup and Restore
How the server is backed up and how to restore the backup?
## Deployment
How to reinstall the server?
Which settings were selected to create the server? E.g. the operating system image.
Are there deployment scripts, and if any, where they are located and how to run them?
# Changelog
## 2023-05-30 - Created the server
Document the steps taken here.
## 2023-06-10 - Installed nginx
...