Browse Source
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.pull/1880/head^2
Daenney
3 years ago
committed by
GitHub
16 changed files with 279 additions and 209 deletions
@ -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. |
||||
@ -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) |
||||
@ -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!). |
||||
|
||||
[](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). |
||||
@ -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. |
||||
@ -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`. |
||||
@ -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! |
||||
@ -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!). |
||||
|
||||
[](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). |
||||
Loading…
Reference in new issue