[docs] Revamp the installation guide (#1877)

This tries to revamp/restructure the installation guide. It's renamed to
"Getting Started" as it now contains a few more things than just the
installation, especially the deployment considerations which we didn't
use to spell out as much ahead of time.

Installation is now a section with the guides on their own. I've removed
a bit of redundancy like the user creation. I also removed the rogue
reverse proxy section in the Docker guide and lifted that into the
reverse proxy section.

docs/getting_started/index.md

@@ -0,0 +1,75 @@
+# Deployment considerations
+
+Before deploying GoToSocial, it's important to think through a few things as some choices will have long-term consequences for how you run and manage GoToSocial.
+
+!!! danger
+
+    It's not supported across the Fediverse to switch between implementations on the same domain. This means that if you run GoToSocial on example.org, you'll run into federation issues if you try to switch to a different implementation like Pleroma/Akkoma, Misskey/Calckey etc.
+    
+    In that same vein, if you already have another ActivityPub implementation running on example.org you should not attempt to switch to GoToSocial on that domain.
+
+## Database
+
+GoToSocial supports both SQLite and Postgres and you can start using either. We do not currently have tooling to support migrating from SQLite to Postgres or vice-versa, but it is possible in theory.
+
+SQLite is great for a single-user instance. If you're planning on hosting multiple people it's advisable to use Postgres instead. You can always use Postgres regardless of the instance size.
+
+!!! tip
+    Please backup your database. The database contains encryption keys for the instance and any user accounts. You won't be able to federate again from the same domain if you lose these keys.
+
+## Domain name
+
+In order to federate with others, you'll need a domain like `example.org`. You can register your domain name through any domain registrar, like [Namecheap](https://www.namecheap.com/). Make sure you pick a registrar that also lets you manage DNS entries, so you can point your domain to the IP of the server that's running your GoToSocial instance.
+
+You'll commonly see usernames existing at the apex of the domain, for example `@me@example.org` but this is not required. It's perfectly fine to have users exist on `@me@social.example.org` instead. Many people prefer to have usernames on the apex as its shorter to type, but you can use any (subdomain) you control.
+
+It is possible to have usernames like `@me@example.org` but have GoToSocial running on `social.example.org` instead. This is done by distinguishing between the API domain, called the "host", and the domain used for usernames, called the "account domain".
+
+!!! danger
+    It's not possible to safely change whether the host and account domain are different after the fact. It requires regenerating the database and will cause confusion for any server you have already federated with.
+
+When using a single domain, you only need to configure the "host" in the GoToSocial configuration:
+
+```yaml
+host: "example.org"
+```
+
+When using a split domain approach, you need to configure both the "host" and the "account-domain":
+
+```yaml
+host: "social.example.org"
+account-domain: "example.org"
+```
+
+## TLS
+
+For federation to work, you have to use TLS. Most implementations, including GoToSocial, will generally refuse to federate over unencrypted transports.
+
+GoToSocial comes with built-in support for provisioning certificates through Lets Encrypt. It can also load certificates from disk. If you have a reverse-proxy in front of GoToSocial you can handle TLS at that level instead.
+
+!!! tip
+    Make sure you configure the use of modern versions of TLS, TLSv1.2 and higher, in order to keep communications between servers and clients safe. When GoToSocial handles TLS termination this is done automatically for you. If you have a reverse-proxy in use, use the [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/).
+
+## Server / VPS
+
+GoToSocial aims to fit in small spaces so we try and ensure that the system requirements are fairly minimal: for a single-user instance with about 100 followers/followees, it uses somewhere between 50 to 100MB of RAM. CPU usage is only intensive when handling media (encoding blurhashes, mostly) and/or doing a lot of federation requests at the same time.
+
+These light requirements mean GtS runs pretty well on something like a Raspberry Pi (a €40 single-board computer). It's been tested on a Raspberry Pi Zero W as well (a €9 computer smaller than a credit card), but it's not quite able to run on that. It should run on a Raspberry Pi Zero W 2 (which costs €14!), but we haven't tested that yet. You can also repurpose an old laptop or desktop to run GoToSocial for you.
+
+If you decide to use a VPS instead, you can spin yourself up something cheap with Linux running on it. Most of the VPS offerings in the €2-€5 range will perform admirably for a personal GoToSocial instance.
+
+[Hostwinds](https://www.hostwinds.com/) is a good option here: it's cheap and they throw in a static IP address for free.
+
+[Greenhost](https://greenhost.net) is also great: it has zero CO2 emissions, but is a bit more costly.
+
+## Ports
+
+GoToSocial needs ports `80` and `443` open.
+
+* `80` is used for Lets Encrypt. As such, you don't need it if you don't use the built-in Lets Encrypt provisioning.
+* `443` is used to serve the API on with TLS and is what any instance you're federating with will try to connect to.
+
+If you can't leave `443` and `80` open on the machine, don't worry! You can configure these ports in GoToSocial, but you'll have to also configure port forwarding to properly forward traffic on `443` and `80` to whatever ports you choose.
+
+!!! tip
+    You should configure a firewall on your machine, as well as some protection against brute-force SSH login attempts and the like. A simple frontend to help you configure your firewall is [UFW](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-18-04). You should also consider a tool like [Fail2Ban](https://linuxize.com/post/install-configure-fail2ban-on-ubuntu-20-04/) in order to automatically block malicious users.

docs/getting_started/installation/container.md

@@ -1,32 +1,10 @@
-# Docker
+# Container
 
-The official GoToSocial Docker images are provided through [Docker Hub](https://hub.docker.com/r/superseriousbusiness/gotosocial).
+This guide walks you through getting GoToSocial up and running using the official container images we publish. In this case we'll be using the Docker runtime directly through [Docker Compose](https://docs.docker.com/compose) together with SQLite as the database.
 
-Docker images are currently available for the following OS + architecture combinations:
+You can also run GoToSocial using a container orchestration system such as [Kubernetes](https://kubernetes.io/) or [Nomad](https://www.nomadproject.io/), but that is beyond the scope of this guide.
 
-Linux
+## Create a Working Directory
-
-- 386
-- amd64
-- arm6
-- arm7
-- arm64v8
-
-FreeBSD
-
-- amd64
-
-Before following this guide, you should read the [system requirements](./index.md).
-
-This guide assumes that you're using Linux.
-
-## Run with Docker Compose
-
-You can run GoToSocial using any orchestration system that can manage Docker containers ([Kubernetes](https://kubernetes.io/), [Nomad](https://www.nomadproject.io/), etc).
-
-For simplicity's sake, this guide will lead you through the installation with [Docker Compose](https://docs.docker.com/compose), using SQLite as your database.
-
-### Create a Working Dir
 
 You need a working directory in which your docker-compose file will be located, and a directory for GoToSocial to store data in, so create these directories with the following command:
 
@@ -40,7 +18,7 @@ Now change to the working directory you created:
 cd ~/gotosocial
 ```
 
-### Get the latest docker-compose.yaml
+## Get the latest docker-compose.yaml
 
 Use `wget` to download the latest [docker-compose.yaml](https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml) example, which we'll customize for our needs:
 
@@ -48,9 +26,9 @@ Use `wget` to download the latest [docker-compose.yaml](https://raw.githubuserco
 wget https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/docker-compose/docker-compose.yaml
 ```
 
-### Edit the docker-compose.yaml
+## Edit the docker-compose.yaml
 
-Because GoToSocial can be configured using [Environment Variables](../configuration/index.md#environment-variables), we can skip mounting a config.yaml file into the container, to make our configuration simpler. We just need to edit the docker-compose.yaml file to change a few things.
+Because GoToSocial can be configured using [Environment Variables](../../configuration/index.md#environment-variables), we can skip mounting a config.yaml file into the container, to make our configuration simpler. We just need to edit the docker-compose.yaml file to change a few things.
 
 First open the docker-compose.yaml file in your editor of choice. For example:
 
@@ -58,7 +36,7 @@ First open the docker-compose.yaml file in your editor of choice. For example:
 nano docker-compose.yaml
 ```
 
-#### Version
+### Version
 
 If desired, update the GoToSocial Docker image tag to the version of GtS you want to use.
 
@@ -80,54 +58,25 @@ with:
 image: superseriousbusiness/gotosocial:0.3.1
 ```
 
-#### Host
+### Host
 
 Change the `GTS_HOST` environment variable to the domain you are running GoToSocial on.
 
-#### User (optional / probably not necessary)
+### User (optional / probably not necessary)
 
 By default, Dockerized GoToSocial runs with Linux user/group `1000:1000`, which is fine in most cases. If you want to run as a different user/group, you should change the `user` field in the docker-compose.yaml accordingly.
 
 For example, let's say you created the `~/gotosocial/data` directory for a user with id `1001`, and group id `1001`. If you now try to run GoToSocial without changing the `user` field, it will get a permissions error trying to open its database file in the directory. In this case, you would have to change the `user` field of the docker compose file to `1001:1001`.
 
-#### LetsEncrypt (optional)
+### LetsEncrypt (optional)
 
-If you want to use [LetsEncrypt](../configuration/tls.md) for ssl certificates (https), you should also:
+If you want to use [LetsEncrypt](../../configuration/tls.md) for TLS certificates (https), you should also:
 
 1. Change the value of `GTS_LETSENCRYPT_ENABLED` to `"true"`.
 2. Remove the `#` before `- "80:80"` in the `ports` section.
 3. (Optional) Set `GTS_LETSENCRYPT_EMAIL_ADDRESS` to a valid email address to receive certificate expiry warnings etc.
 
-#### Reverse proxies
+## Start GoToSocial
-
-The default port bindings are for exposing GoToSocial directly and publicly. Remove the `#` in front the line that forwards `127.0.0.1:8080:8080` which makes port `8080` available only to the local host. Change that `127.0.0.1` if the reverse proxy is somewhere else.
-
-To ensure [rate limiting](../api/ratelimiting.md) by IP works, remove the `#` in front of `GTS_TRUSTED_PROXIES` and set it to the IP the requests from the reverse proxy are coming from. That's usually the value of the `Gateway` field of the docker network.
-
-```text
-$ docker network inspect gotosocial_gotosocial
-[
-    {
-        "Name": "gotosocial_gotosocial",
-        [...]
-        "IPAM": {
-            "Driver": "default",
-            "Options": null,
-            "Config": [
-                {
-                    "Subnet": "172.19.0.0/16",
-                    "Gateway": "172.19.0.1"
-                }
-            ]
-        },
-        [...]
-```
-
-In the example above, it would be `172.19.0.1`.
-
-If unsure, skip the trusted proxies step, continue with the next sections, and once it's running get the `clientIP` from the docker logs.
-
-### Start GoToSocial
 
 With those small changes out of the way, you can now start GoToSocial with the following command:
 
@@ -161,39 +110,9 @@ time=2022-04-19T09:48:36Z level=info msg=started media manager remote cache clea
 time=2022-04-19T09:48:36Z level=info msg=listening on 0.0.0.0:8080
 ```
 
-### Create your first User
+## Create your first User
 
-Now that GoToSocial is running, you can execute commands inside the running container to create and promote your admin user.
+Now that GoToSocial is running, you should create at least a user for yourself. How to do so is documented in our [Creating users](../user_creation.md) guide.
-
-First create a user (replace the username, email, and password with appropriate values):
-
-```bash
-docker exec -it gotosocial /gotosocial/gotosocial admin account create --username some_username --email someone@example.org --password 'some_very_good_password'
-```
-
-If you are running a version older than 0.6.0, you will need to manually confirm as well:
-
-```bash
-./gotosocial --config-path ./config.yaml admin account confirm --username some_username
-```
-
-Replace `some_username` with the username of the account you just created.
-
-Now promote the user you just created to admin privileges:
-
-```bash
-docker exec -it gotosocial /gotosocial/gotosocial admin account promote --username some_username
-```
-
-When running these commands, you'll get a bit of output like the following:
-
-```text
-time=2022-04-19T09:53:29Z level=info msg=connected to SQLITE database
-time=2022-04-19T09:53:29Z level=info msg=there are no new migrations to run func=doMigration
-time=2022-04-19T09:53:29Z level=info msg=closing db connection
-```
-
-This is normal and indicates that the commands ran as expected.
 
 ### Done
 
@@ -201,4 +120,4 @@ GoToSocial should now be running on your machine! To verify this, open your brow
 
 ## (Optional) Reverse Proxy
 
-If you want to run other webservers on port 443, or want to add an additional layer of security you might want to add [NGINX](https://nginx.org), [Traefik](https://doc.traefik.io/traefik/), or [Apache httpd](https://httpd.apache.org/) into your docker-compose to use as a reverse proxy.
+If you want to run other webservers on port 443 or want to add an additional layer of security you might want to use a [reverse proxy](../reverse_proxy/index.md). We have guides available for a couple of popular open source options and will gladly take pull requests to add more.

docs/getting_started/installation/index.md

@@ -0,0 +1,14 @@
+# Installation
+
+As we noted in [Releases](../releases.md), we publish official binary release as well as containers. We have a number of guides available on how to deploy your own GoToSocial instance this way.
+
+Before proceeding with your installation, please ensure you've read through the [Deployment considerations](../index.md) first and have a domain and server ready to go.
+
+Also take a minute to familiarise yourself with [how to configure](../../configuration/index.md) GoToSocial.
+
+## Guides
+
+For third-party releases we don't provide guides on how to use them. You need to refer to their own documentation instead. Our guides might still be useful to review in order to familiarise yourself with which configuration options you likely want to set and tweak.
+
+* [Bare metal](metal.md)
+* [Container](container.md)

docs/getting_started/installation/metal.md

@@ -1,8 +1,8 @@
-# Binary Installation From Release
+# Bare metal
 
-This is the binary installation guide for GoToSocial. It is assumed that you already have a [properly configured VPS running in the cloud, or a suitable homeserver that is accessible with port forwarding](index.md).
+This guide walks you through getting GoToSocial up and running on bare metal using the official binary releases.
 
-## 1: Prepare VPS
+## Prepare VPS
 
 In a terminal on the VPS or your homeserver, make the directory that GoToSocial will run from, the directory it will use as storage, and the directory it will store LetsEncrypt certificates in:
 
@@ -12,7 +12,7 @@ mkdir /gotosocial && mkdir /gotosocial/storage && mkdir /gotosocial/storage/cert
 
 If you don't have root permissions on the machine, use something like `~/gotosocial` instead.
 
-## 2: Download Release
+## Download Release
 
 In a terminal on the VPS or your homeserver, cd into the base directory for GoToSocial you just created above:
 
@@ -38,7 +38,7 @@ tar -xzf gotosocial_0.5.2_linux_amd64.tar.gz
 
 This will put the `gotosocial` binary in your current directory, in addition to the `web` folder, which contains assets for the web frontend, and an `example` folder, which contains a sample configuration file.
 
-## 3. Edit Configuration File
+## Edit Configuration File
 
 Copy the configuration file from the example folder into your current directory:
 
@@ -56,9 +56,9 @@ Now open the file in your text editor of choice so that you can set some importa
 - Set `letsencrypt-enabled` to `true`.
 - Set `letsencrypt-cert-dir` to the certificate storage directory you created above (eg., `/gotosocial/storage/certs`).
 
-The above options assume you're using SQLite as your database. If you want to use Postgres instead, see [here](../configuration/database.md) for the config options.
+The above options assume you're using SQLite as your database. If you want to use Postgres instead, see [here](../../configuration/database.md) for the config options.
 
-## 4: Run the Binary
+## Run the Binary
 
 You can now run the binary.
 
@@ -72,40 +72,15 @@ The server should now start up and you should be able to access the splash page
 
 Note that for this example we're assuming that we're allowed to run on port 443 (standard https port), and that nothing else is running on this port.
 
-## 5: Create your user
+## Create your user
 
-You can use the GoToSocial binary to also create and promote your user account.
+You can use the GoToSocial binary to also create and promote your user account. This is all documented in our [Creating users](../user_creation.md) guide.
 
-Run the following command to create a new account:
+## Login
-
-```bash
-./gotosocial --config-path ./config.yaml admin account create --username some_username --email some_email@whatever.org --password 'SOME_PASSWORD'
-```
-
-In the above command, replace `some_username` with your desired username, `some_email@whatever.org` with the email address you want to associate with your account, and `SOME_PASSWORD` with a secure password.
-
-If you are running a version older than 0.6.0, you will need to manually confirm as well:
-
-```bash
-./gotosocial --config-path ./config.yaml admin account confirm --username some_username
-```
-
-Replace `some_username` with the username of the account you just created.
-
-
-If you want your user to have admin rights, you can promote them using a similar command:
-
-```bash
-./gotosocial --config-path ./config.yaml admin account promote --username some_username
-```
-
-Replace `some_username` with the username of the account you just created.
-
-## 6. Login
 
 You should now be able to log in to your instance using the email address and password of the account you just created. We recommend using [Semaphore](https://semaphore.social) or [Tusky](https://tusky.app) for this.
 
-## 7. \[Optional\] Enable the systemd service
+## (Optional) Enable the systemd service
 
 If you don't like manually starting GoToSocial on every boot you might want to create a systemd service that does that for you.
 
@@ -143,6 +118,6 @@ After you're done enable the service:
 sudo systemctl enable --now gotosocial.service
 ```
 
-## 8. \[Optional\] Reverse proxy
+## (Optional) Reverse proxy
 
-If you want to run other webservers on port 443 or want to add an additional layer of security you might want to use [nginx](./nginx.md), [Caddy](./caddy.md) or [Apache httpd](./apache-httpd.md) as reverse proxy
+If you want to run other webservers on port 443 or want to add an additional layer of security you might want to use a [reverse proxy](../reverse_proxy/index.md). We have guides available for a couple of popular open source options and will gladly take pull requests to add more.

docs/getting_started/releases.md

@@ -0,0 +1,40 @@
+# Releases
+
+GoToSocial can be installed in a number of different ways. We publish official binary releases as well as container images. A number of third-party packages are maintained by different distributions and some people have created additional deployment tooling to make it easy to deploy GoToSocial yourself.
+
+## Binary releases
+We publish binary builds for Linux to [our GitHub project](https://github.com/superseriousbusiness/gotosocial/releases):
+
+* 32-bit Intel/AMD (i386/x86)
+* 64-bit Intel/AMD (amd64/x86_64)
+* 32-bit ARM (v6 and v7)
+* 64-bit ARM64
+
+For FreeBSD we publish:
+
+* 64-bit Intel/AMD (amd64/x86_64)
+
+## Containers
+
+We also publish container images [on the Docker Hub](https://hub.docker.com/r/superseriousbusiness/gotosocial).
+
+Containers are released for the same Linux platforms as our binary releases, with the exception of 32-bit Intel/AMD.
+
+## Third-party
+
+Some folks have created distribution packages for GoToSocial or additional tooling to aid in installing GoToSocial.
+
+### Distribution packages
+
+These packages are not maintained by GoToSocial, so please direct questions and issues to the repository maintainers (and donate to them!).
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/gotosocial.svg)](https://repology.org/project/gotosocial/versions)
+
+### Deployment tools
+
+You can deploy your own instance of GoToSocial with the help of:
+
+- [YunoHost GoToSocial Packaging](https://github.com/YunoHost-Apps/gotosocial_ynh) by [OniriCorpe](https://github.com/OniriCorpe).
+- [Ansible Playbook (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook): The playbook supports a many services, including GoToSocial. [Documentation](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/gotosocial.md)
+- GoToSocial Helm Charts:
+  - [GoToSocial Helm Chart](https://github.com/fSocietySocial/charts/tree/main/charts/gotosocial) by [0hlov3](https://github.com/0hlov3).

docs/getting_started/reverse_proxy/apache-httpd.md

@@ -1,4 +1,4 @@
-# Reverse proxy with Apache HTTP Server
+# Apache HTTP Server
 
 ## Requirements
 
@@ -127,7 +127,7 @@ You should also change `http://127.0.0.1:8080` to the correct address and port (
 
 `ProxyPreserveHost On` is essential: It guarantees that the proxy and the GoToSocial speak of the same Server name. If not, GoToSocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401 Unauthorized.
 
-By default, apache sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../api/ratelimiting.md) and [general configuration](../configuration/general.md) docs
+By default, apache sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
 
 Save and close the config file.
 
@@ -206,7 +206,7 @@ Again, replace occurrences of `example.com` in the above config file with the ho
 
 You should also change `http://127.0.0.1:8080` to the correct address and port (if it's not on `127.0.0.1:8080`) of your GtS server. For example, if you're running GoToSocial on another machine with the local ip of `192.168.178.69` and on port `8080` then `http://192.168.178.69:8080/` would be the correct value.
 
-`Rewrite*` directives are needed to ensure that Websocket streaming connections also work. See the [websocket](./websocket.md) document for more information on this.
+`Rewrite*` directives are needed to ensure that Websocket streaming connections also work. See the [websocket](websocket.md) document for more information on this.
 
 `ProxyPreserveHost On` is essential: It guarantees that the proxy and the GoToSocial speak of the same Server name. If not, GoToSocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401 Unauthorized.
 

docs/getting_started/reverse_proxy/caddy.md

@@ -1,4 +1,4 @@
-# Reverse proxy with Caddy 2
+# Caddy 2
 
 ## Requirements
 
@@ -79,7 +79,7 @@ example.org {
 }
 ```
 
-By default, caddy sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../api/ratelimiting.md) and [general configuration](../configuration/general.md) docs
+By default, caddy sets `X-Forwarded-For` in forwarded requests. To make this and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
 
 For advanced configuration check the [reverse_proxy directive](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) at the Caddy documentation.
 

docs/getting_started/reverse_proxy/index.md

@@ -0,0 +1,43 @@
+# Reverse proxy
+
+GoToSocial can be exposed directly to the internet. However, many folks prefer to have a reverse proxy handle connections from the outside instead. This can also give greater control over TLS configurations and enables some more advanced scenario's like asset caching.
+
+## General procedure
+
+In order to use a reverse-proxy, you'll typically want to do a few things:
+
+* Configure some way to get TLS certificates for the host domain
+* Bind GoToSocial to a local IP instead of a public IP and a non-priviledged port. Adjust the `bind-address` and `port` configuration options
+* Disable Lets Encrypt in GoToSocial if you were using it. Set `letsencrypt-enabled` to `false`
+* Configure the reverse proxy to handle TLS and proxy requests to GoToSocial
+
+!!! warning
+    Do not change the value of the `host` configuration option. This needs to remain the actual domain name the instance is running on as seen by other instances on the internet. Instead, change the `bind-address` and update the `port` and `trusted-proxies`.
+
+### Container
+
+When you deploy GoToSocial using our [example Docker Compose guide](../installation/container.md), it will bind to port `443` by default as it assumes you want to directly expose it to the internet. In order to run it behind a reverse proxy, you need to change that.
+
+In the compose file:
+
+* Comment out the `- "443:8080"` line in the `ports` definition
+* If you had enabled Lets Encrypt support:
+    * Comment out the `- "80:80"` line in the `ports` definition
+    * Set `GTS_LETSENCRYPT_ENABLED` back to `"false"` or comment it out
+* Uncomment the `- "127.0.0.1:8080:8080"` line instead
+
+This now causes Docker to only forward connections on `127.0.0.1` on port `8080` to the container, effectively isolating it from the outside world. You can now tell your reverse-proxy to send requests there instead.
+
+## Guides
+
+We have guides available for the following servers:
+
+* [nginx](nginx.md)
+* [Apache httpd](apache-httpd.md)
+* [Caddy 2](caddy.md)
+
+## WebSockets
+
+When using a reverse-proxy, special care must be taken to allow WebSockets to work too. This is necessary as many client applications use WebSockets to stream your timeline. WebSockets is not used as part of federation.
+
+Make sure you read the [WebSocket](websocket.md) documentation and configure your reverse proxy accordingly.

docs/getting_started/reverse_proxy/nginx.md

@@ -1,4 +1,4 @@
-# Reverse proxy with NGINX
+# NGINX
 
 ## Requirements
 
@@ -85,11 +85,11 @@ If you're running GoToSocial on another machine with the local ip of 192.168.178
 
 **Note**: `proxy_set_header Host $host;` is essential. It guarantees that the proxy and GoToSocial use the same server name. If not, GoToSocial will build the wrong authentication headers, and all attempts at federation will be rejected with 401.
 
-**Note**: The `Connection` and `Upgrade` headers are used for WebSocket connections. See the [WebSocket docs](./websocket.md).
+**Note**: The `Connection` and `Upgrade` headers are used for WebSocket connections. See the [WebSocket docs](websocket.md).
 
 **Note**: `client_max_body_size` is set to 40M in this example, which is the default max video upload size for GoToSocial. You can make this value larger or smaller if necessary. The nginx default is only 1M, which is rather too small.
 
-**Note**: To make `X-Forwarded-For` and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../api/ratelimiting.md) and [general configuration](../configuration/general.md) docs
+**Note**: To make `X-Forwarded-For` and rate limiting work, set the `trusted-proxies` configuration variable. See the [rate limiting](../../api/ratelimiting.md) and [general configuration](../../configuration/general.md) docs
 
 Next we'll need to link the file we just created to the folder that nginx reads configurations for active sites from.
 
@@ -183,4 +183,4 @@ server {
 }
 ```
 
-A number of additional configurations for nginx, including static asset serving and caching, are documented in the [Advanced](advanced.md) section of our documentation.
+A number of additional configurations for nginx, including static asset serving and caching, are documented in the [Advanced](../advanced.md) section of our documentation.

docs/getting_started/reverse_proxy/websocket.md

@@ -6,7 +6,7 @@ In order to use this functionality, you need to ensure that whatever proxy you'v
 
 The WebSocket endpoint is located at `wss://example.org/api/v1/streaming` where `example.org` is the hostname of your GoToSocial instance.
 
-The WebSocket endpoint uses the same port as configured in the `port` section of your [general config](../configuration/general.md).
+The WebSocket endpoint uses the same port as configured in the `port` section of your [general config](../../configuration/general.md).
 
 Typical WebSocket **request** headers as sent by Pinafore look like the following:
 

docs/getting_started/tracing.md

@@ -16,7 +16,7 @@ tracing-insecure: true
 ```
 
 [otel]: https://opentelemetry.io/
-[obs]: ../../configuration/observability/
+[obs]: ../configuration/observability.md
 [tempo]: https://grafana.com/oss/tempo/
 [grafana]: https://grafana.com/oss/grafana/
 [ext]: https://github.com/superseriousbusiness/gotosocial/tree/main/example/tracing
@@ -25,7 +25,7 @@ tracing-insecure: true
 
 Once you execute a few queries against your instance, you'll be able to find them in Grafana. You can use the Explore tab and pick Tempo as the datasource. Because our example configuration for Grafana enables [TraceQL][traceql], the Explore tab will have the TraceQL query type selected by default. You can switch to "Search" instead and find all traces emitted by GoToSocial under the "GoToSocial" service name.
 
-Using TraceQL, a simple TraceQL query to find all traces related to requests to `/api/v1/instance` would look like this:
+Using TraceQL, a simple query to find all traces related to requests to `/api/v1/instance` would look like this:
 
 ```
 {.http.route = "/api/v1/instance"}

docs/getting_started/user_creation.md

@@ -0,0 +1,50 @@
+# Creating users
+
+Regardless of the installation method, you'll need to create some users. GoToSocial currently doesn't have a way for users to be created through the web UI, or for people to sign-up through the web UI.
+
+Using the CLI, you can create a user:
+
+```sh
+$ gotosocial --config-path /path/to/config.yaml \
+    admin account create \
+    --username some_username \
+    --email some_email@whatever.org \
+    --password 'SOME_PASSWORD'
+```
+
+In the above command, replace `some_username` with your desired username, `some_email@whatever.org` with the email address you want to associate with your account, and `SOME_PASSWORD` with a secure password.
+
+If you want your user to have admin rights, you can promote them using a similar command:
+
+```sh
+$ gotosocial --config-path /path/to/config.yaml \
+    admin account promote --username some_username
+```
+
+Replace `some_username` with the username of the account you just created.
+
+!!! info
+    When running these commands, you'll get a bit of output like the following:
+
+    ```text
+    time=XXXX level=info msg=connected to SQLITE database
+    time=XXXX level=info msg=there are no new migrations to run func=doMigration
+    time=XXXX level=info msg=closing db connection
+    ```
+
+    This is normal and indicates that the commands ran as expected.
+
+## Containers
+
+When running GoToSocial from a container, you'll need to execute the above command in the conatiner instead. How to do this varies based on your container runtime, but for Docker it should look like:
+
+```sh
+$ docker exec -it CONTAINER_NAME_OR_ID \
+    /gotosocial/gotosocial \
+    admin account create \
+    --username some_username \
+    --email someone@example.org \
+    --password 'some_very_good_password'
+```
+
+If you followed our Docker guide, the container name will be `gotosocial`. Both the name and the ID can be retrieved through `docker ps`.

docs/installation_guide/index.md

@@ -1,33 +0,0 @@
-# System Requirements
-
-GoToSocial needs a domain name, and a *server* to run on, either a homeserver in your house, or a cloud server.
-
-## Server / VPS
-
-The system requirements for GoToSocial are fairly minimal: for a single-user instance with about 100 followers/followees, it uses somewhere between 50 to 100MB of RAM. CPU usage is only intensive when handling media (encoding blurhashes, mostly) and/or doing a lot of federation requests at the same time.
-
-These light requirements mean GtS runs pretty well on something like a Raspberry Pi (a €40 single-board computer). It's been tested on a Raspberry Pi Zero W as well (a €9 computer smaller than a credit card), but it's not quite able to run on that. It should run on a Raspberry Pi Zero W 2 (which costs €14!), but we haven't tested that yet.
-
-If you have an old laptop or a dusty desktop lying around that you're not using anymore, it will probably be a perfect candidate for running GoToSocial.
-
-If you decide to use a VPS instead, you can just spin yourself up something cheap with Linux running on it.
-
-[Hostwinds](https://www.hostwinds.com/) is a good option here: it's cheap and they throw in a static IP address for free.
-
-[Greenhost](https://greenhost.net) is also great: it has zero co2 emissions, but is a bit more costly.
-
-## Ports
-
-The installation guides won't go into running [UFW](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-18-04) and [Fail2Ban](https://linuxize.com/post/install-configure-fail2ban-on-ubuntu-20-04/) but you absolutely should do that.
-
-For ports, you should leave `443` and `80` open. `443` is used for https requests to GoToSocial, and `80` is used for LetsEncrypt certification verification.
-
-If you can't leave `443` and `80` open on the machine, don't worry! You can configure these ports in GoToSocial, but you'll have to also configure port forwarding to properly forward traffic on `443` and `80` to whatever ports you choose.
-
-## Domain Name
-
-To run a GoToSocial server, you also need a domain name, and it needs to be pointed towards your VPS or homeserver.
-
-[Namecheap](https://www.namecheap.com/) is a good place to do this, but you can use any domain name registrar that lets you manage your own DNS.
-
-IMPORTANT: If you want to host GoToSocial at a different host from your desired account domain (eg., you want to host GtS at `fedi.example.org` but you want your account to show up at `example.org`), please read the [advanced configuration](./advanced.md) carefully, before proceeding with installation!

docs/installation_guide/third_party.md

@@ -1,18 +0,0 @@
-# Third-Party Packaging
-
-Several awesome people have put time and energy into packaging GoToSocial for third-party ecosystems.
-
-## Distribution packaging
-
-These packages are not maintained by GoToSocial, so please direct questions and issues to the repository maintainers (and donate to them!).
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/gotosocial.svg)](https://repology.org/project/gotosocial/versions)
-
-## Self-hosting
-
-You can deploy your own instance of GoToSocial with the help of:
-
-- [YunoHost GoToSocial Packaging](https://github.com/YunoHost-Apps/gotosocial_ynh) by [OniriCorpe](https://github.com/OniriCorpe).
-- [Ansible Playbook (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook): The playbook supports a many services, including GoToSocial. [Documentation](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/gotosocial.md)
-- GoToSocial Helm Charts:
-  - [GoToSocial Helm Chart](https://github.com/fSocietySocial/charts/tree/main/charts/gotosocial) by [0hlov3](https://github.com/0hlov3).

mkdocs.yml

@@ -53,17 +53,22 @@ nav:
       - "user_guide/custom_css.md"
       - "user_guide/password_management.md"
       - "user_guide/rss.md"
-  - "Installation Guide":
+  - "Getting Started":
-      - "installation_guide/index.md"
+      - "getting_started/index.md"
-      - "installation_guide/binary.md"
+      - "getting_started/releases.md"
-      - "installation_guide/docker.md"
+      - "Installation":
-      - "installation_guide/nginx.md"
+        - "getting_started/installation/index.md"
-      - "installation_guide/apache-httpd.md"
+        - "getting_started/installation/metal.md"
-      - "installation_guide/caddy.md"
+        - "getting_started/installation/container.md"
-      - "installation_guide/third_party.md"
+      - "Reverse Proxy":
-      - "installation_guide/websocket.md"
+        - "getting_started/reverse_proxy/index.md"
-      - "installation_guide/advanced.md"
+        - "getting_started/reverse_proxy/nginx.md"
-      - "installation_guide/tracing.md"
+        - "getting_started/reverse_proxy/apache-httpd.md"
+        - "getting_started/reverse_proxy/caddy.md"
+        - "getting_started/reverse_proxy/websocket.md"
+      - "getting_started/advanced.md"
+      - "getting_started/user_creation.md"
+      - "getting_started/tracing.md"
   - "Configuration":
       - "configuration/index.md"
       - "configuration/general.md"