SuperSeriousBusiness/GoToSocial
1
1
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial synced 2025-06-05 21:59:39 +02:00
Code Issues Projects Releases Wiki Activity

Update docs with better config + installation instructions (#300)

Browse Source 
* start reworking some documentation

* fuller documentation  + better docs structure
This commit is contained in:
tobi
2021-11-14 16:54:23 +01:00
committed by GitHub
parent 38e100a7a4
commit d81a123473
21 changed files with 718 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/installation_guide/binary.md
View File

@@ -1,3 +1,107 @@
# Binary Installation
# Binary Installation From Release
TODO
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).
## 1: 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:
```bash
mkdir /gotosocial && mkdir /gotosocial/storage && mkdir /gotosocial/storage/certs
```
If you don't have root permissions on the machine, use something like `~/gotosocial` instead.
## 2: Download Release
In a terminal on the VPS or your homeserver, cd into the base directory for GoToSocial you just created above:
```bash
cd /gotosocial
```
Now, download the latest GoToSocial release archive corresponding to the operating system and architecture you're running on.
For example, for version 0.1.0 running on 64-bit Linux:
```bash
wget https://github.com/superseriousbusiness/gotosocial/releases/download/v0.1.0/gotosocial_0.1.0_linux_amd64.tar.gz
```
Then extract it:
```bash
tar -xzf gotosocial_0.1.0_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
Copy the configuration file from the example folder into your current directory:
```bash
cp ./example/config.yaml .
```
Now open the file in your text editor of choice so that you can set some important configuration values. Change the following settings:
* Set `host` to whatever hostname you're going to be running the server on (eg., `example.org`).
* Set `port` to `443`.
* Set `db.type` to `sqlite`.
* Set `db.address` to `sqlite.db`.
* Set `storage.basePath` to the storage directory you created above (eg., `/gotosocial/storage`).
* Set `storage.serveHost` to whatever you set the `host` value to above (eg., `example.org`).
* Set `letsEncrypt.certDir` 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.
## 4: Run the Binary
You can now run the binary.
Start the GoToSocial server with the following command:
```bash
./gotosocial --config-path ./config.yaml server start
```
The server should now start up and you should be able to access the splash page by navigating to your domain in the browser. Note that it might take up to a minute or so for your LetsEncrypt certificates to be created for the first time, so refresh a few times if necessary.
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 and confirm your user
You can use the GoToSocial binary to also create, confirm, and promote your user account.
Run the following command to create a new account:
```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.
Run the following command to confirm the account you just created:
```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 [Pinafore](https://pinafore.social) or [Tusky](https://tusky.app) for this.
## 7. Install the Admin Control Panel (optional)
At some point you'll likely want to do things like change instance information, and block domains you don't want to interact with. See the [admin panel](../admin/admin_panel.md) instructions for this.

31
docs/installation_guide/index.md Normal file
View File

@@ -0,0 +1,31 @@
# 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.

146
docs/installation_guide/quick_and_dirty.md
View File

@@ -1,146 +0,0 @@
# Quick and Dirty <!-- omit in toc -->
This is the quick and dirty getting started guide. It's not recommended to run GtS like this in production, but if you want to quickly get a server up and running, this is a good way to do it.
## Table of Contents <!-- omit in toc -->
- [1: Domain Name](#1-domain-name)
- [2: VPS](#2-vps)
- [3: DNS](#3-dns)
- [4: Postgres](#4-postgres)
- [5: Build the Binary](#5-build-the-binary)
- [6: Prepare VPS](#6-prepare-vps)
- [7: Copy Binary](#7-copy-binary)
- [8: Copy Web Dir](#8-copy-web-dir)
- [9: Run the Binary](#9-run-the-binary)
- [10: Create and confirm your user](#10-create-and-confirm-your-user)
- [Create](#create)
- [Confirm](#confirm)
- [Promote](#promote)
- [11. Login](#11-login)
## 1: Domain Name
Get a domain name -- [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.
## 2: VPS
Spin yourself up a cheap VPS with Linux running on it, or get a homeserver ready with Ubuntu Server or something similar.
[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.
This guide 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. Leave ports `443` and `80` open.
## 3: DNS
Point your domain name towards the server you just spun up.
## 4: Postgres
Install [Postgres](https://www.postgresql.org/download/) on your server and run it.
If you have [Docker](https://docs.docker.com/engine/install/ubuntu/) installed on your server, this is as easy as running:
```bash
docker run -d --network host --user postgres -e POSTGRES_PASSWORD=some_password postgres
```
## 5: Build the Binary
On your local machine (not your server), with Go installed, clone the GoToSocial repository, and build the binary with the provided build script:
```bash
./scripts/build.sh
```
If you need to build for a different architecture other than the one you're running the build on (eg., you're running on a Raspberry Pi but building on an amd64 machine), you can put set `GOOS` or `GOARCH` environment variables before running the build script, eg:
```bash
GOARCH=arm64 ./scripts/build.sh
```
## 6: Prepare VPS
On the VPS or your homeserver, make the directory that GoToSocial will run from, and the directory it will use as storage:
```bash
mkdir /gotosocial && mkdir /gotosocial/storage
```
## 7: Copy Binary
Copy your binary from your local machine onto the VPS, using something like the following command (where `example.org` is the domain you set up in step 1):
```bash
scp ./gotosocial root@example.org:/gotosocial/gotosocial
```
Replace `root` with whatever user you're actually running on your remote server (you wouldn't run as root right? ;).
## 8: Copy Web Dir
GoToSocial uses some web templates and static assets, so you need to copy these over to your VPS as well (where `example.org` is the domain you set up in step 1):
```bash
scp -r ./web root@example.org:/gotosocial/
```
## 9: Run the Binary
You can now run the binary.
First cd into the directory you created on your remote machine in step 6:
```bash
cd /gotosocial
```
Then start the GoToSocial server with the following command (where `example.org` is the domain you set up in step 1, and `some_password` is the password you set for Postgres in step 4):
```bash
./gotosocial --host example.org --port 443 --storage-serve-host example.org --letsencrypt-enabled=true server start
```
The server should now start up and you should be able to access the splash page by navigating to your domain in the browser. Note that it might take up to a minute or so for your LetsEncrypt certificates to be created for the first time, so refresh a few times if necessary.
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.
## 10: Create and confirm your user
You can use the GoToSocial binary to also create, confirm, and promote your user account.
### Create
Run the following command to create a new account:
```bash
./gotosocial --host example.org admin account create --username some_username --email some_email@whatever.org --password SOME_PASSWORD
```
In the above command, replace `example.org` with your domain, `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.
### Confirm
Run the following command to confirm the account you just created:
```bash
./gotosocial --host example.org admin account confirm --username some_username
```
Replace `example.org` with your domain and `some_username` with the username of the account you just created.
### Promote
If you want your user to have admin rights, you can promote them using a similar command:
```bash
./gotosocial --host example.org admin account promote --username some_username
```
Replace `example.org` with your domain and `some_username` with the username of the account you just created.
## 11. 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 [Pinafore](https://pinafore.social) or [Tusky](https://tusky.app) for this.