mirror of
https://github.com/superseriousbusiness/gotosocial.git
synced 2024-11-21 16:55:38 +03:00
Update docs with better config + installation instructions (#300)
* start reworking some documentation * fuller documentation + better docs structure
This commit is contained in:
tobi
GitHub
parent
38e100a7a4
commit
d81a123473
21 changed files with 718 additions and 331 deletions
|
|
@ -154,9 +154,7 @@ These cool things will be implemented if time allows (because we really want the
|
|||
|
||||
## Getting Started
|
||||
|
||||
Proper documentation for running and maintaining GoToSocial will be forthcoming in the first release.
|
||||
|
||||
For now (if you want to run it pre-alpha, like a beast), check out the [quick and dirty getting started guide](https://docs.gotosocial.org/en/latest/installation_guide/quick_and_dirty/).
|
||||
All docs for installation and configuration are hosted at [docs.gotosocial.org](https://docs.gotosocial.org).
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -180,11 +178,11 @@ The following libraries and frameworks are used by GoToSocial, with gratitude
|
|||
- [gin-contrib/cors](https://github.com/gin-contrib/cors); Gin CORS middleware. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [gin-contrib/sessions](https://github.com/gin-contrib/sessions); Gin sessions middleware. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [gin-contrib/static](https://github.com/gin-contrib/static); Gin static page middleware. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [go-fed/activity](https://github.com/go-fed/activity); Golang ActivityPub/ActivityStreams library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [go-fed/httpsig](https://github.com/go-fed/httpsig); secure HTTP signature library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [google/uuid](https://github.com/google/uuid); UUID generation. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html)
|
||||
- [go-playground/validator](https://github.com/go-playground/validator); struct validation. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [gorilla/websocket](https://github.com/gorilla/websocket); Websocket connectivity. [BSD-2-Clause License](https://spdx.org/licenses/BSD-2-Clause.html).
|
||||
- [gruf/go-store](https://codeberg.org/gruf/go-store); cacheing library. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [h2non/filetype](https://github.com/h2non/filetype); filetype checking. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [jackc/pgx](https://github.com/jackc/pgx); Postgres driver. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [microcosm-cc/bluemonday](https://github.com/microcosm-cc/bluemonday); HTML user-input sanitization. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
|
|
@ -200,6 +198,7 @@ The following libraries and frameworks are used by GoToSocial, with gratitude
|
|||
- [sirupsen/logrus](https://github.com/sirupsen/logrus); logging. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [stretchr/testify](https://github.com/stretchr/testify); test framework. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [superseriousbusiness/exifremove](https://github.com/superseriousbusiness/exifremove) forked from [scottleedavis/go-exif-remove](https://github.com/scottleedavis/go-exif-remove); EXIF data removal. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [superseriousbusiness/activity](https://github.com/superseriousbusiness/activity) forked from [go-fed/activity](https://github.com/go-fed/activity); Golang ActivityPub/ActivityStreams library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [superseriousbusiness/oauth2](https://github.com/superseriousbusiness/oauth2) forked from [go-oauth2/oauth2](https://github.com/go-oauth2/oauth2); oauth server framework and token handling. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [go-swagger/go-swagger](https://github.com/go-swagger/go-swagger); Swagger OpenAPI spec generation. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html).
|
||||
- [tdewolff/minify](https://github.com/tdewolff/minify); HTML minification. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
|
|
@ -221,6 +220,8 @@ In alphabetical order:
|
|||
|
||||
### Special Thanks
|
||||
|
||||
A huge thank you to CJ from [go-fed](https://github.com/go-fed/activity): without your work GoToSocial would not have been possible.
|
||||
|
||||
Thanks to everyone who has used GtS, opened an issue, suggested something, given funding, and otherwise encouraged or supported the project!
|
||||
|
||||
## Sponsorship + Funding
|
||||
|
|
|
|||
5
docs/admin/admin_panel.md
Normal file
5
docs/admin/admin_panel.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Admin Control Panel
|
||||
|
||||
TODO!
|
||||
|
||||
For now see [here](https://github.com/superseriousbusiness/gotosocial-admin).
|
||||
27
docs/configuration/accounts.md
Normal file
27
docs/configuration/accounts.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
# Accounts
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
###########################
|
||||
##### ACCOUNTS CONFIG #####
|
||||
###########################
|
||||
|
||||
# Config pertaining to creation and maintenance of accounts on the server, as well as defaults for new accounts.
|
||||
accounts:
|
||||
|
||||
# Bool. Do we want people to be able to just submit sign up requests, or do we want invite only?
|
||||
# Options: [true, false]
|
||||
# Default: true
|
||||
openRegistration: true
|
||||
|
||||
# Bool. Do sign up requests require approval from an admin/moderator before an account can sign in/use the server?
|
||||
# Options: [true, false]
|
||||
# Default: true
|
||||
requireApproval: true
|
||||
|
||||
# Bool. Are sign up requests required to submit a reason for the request (eg., an explanation of why they want to join the instance)?
|
||||
# Options: [true, false]
|
||||
# Default: true
|
||||
reasonRequired: true
|
||||
```
|
||||
98
docs/configuration/database.md
Normal file
98
docs/configuration/database.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
# Database
|
||||
|
||||
GoToSocial stores statuses, accounts, etc, in a database. This can be either [SQLite](https://sqlite.org/index.html) or [Postgres](https://www.postgresql.org/).
|
||||
|
||||
By default, GoToSocial will use Postgres, but this is easy to change.
|
||||
|
||||
## SQLite
|
||||
|
||||
SQLite, as the name implies, is the lightest database type that GoToSocial can use. It stores entries in a simple file format, usually in the same directory as the GoToSocial binary itself. SQLite is great for small instances and lower-powered machines like Raspberry Pi, where a dedicated database would be overkill.
|
||||
|
||||
To configure GoToSocial to use SQLite, change `db.type` to `sqlite`. The `address` setting will then be a filename instead of an address, so you might want to change it to `sqlite.db` or something similar.
|
||||
|
||||
Note that the `:memory:` setting will use an *in-memory database* which will be wiped when your GoToSocial instance stops running. This is for testing only and is absolutely not suitable for running a proper instance, so *don't do this*.
|
||||
|
||||
## Postgres
|
||||
|
||||
Postgres is a heavier database format, which is useful for larger instances where you need to scale performance, or where you need to run your database on a dedicated machine separate from your GoToSocial instance (or do funky stuff like run a database cluster).
|
||||
|
||||
GoToSocial supports connecting to Postgres using SSL/TLS. If you're running Postgres on a different machine from GoToSocial, and connecting to it via an IP address or hostname (as opposed to just running on localhost), then SSL/TLS is **CRUCIAL** to avoid leaking data all over the place!
|
||||
|
||||
When you're using Postgres, GoToSocial expects whatever you've set for `db.user` to already be created in the database, and to have ownership of whatever you've set for `db.database`.
|
||||
|
||||
For example, if you set:
|
||||
|
||||
```text
|
||||
db:
|
||||
[...]
|
||||
user: "gotosocial"
|
||||
password: "some_really_good_password"
|
||||
database: "gotosocial"
|
||||
```
|
||||
|
||||
Then you should have already created database `gotosocial` in Postgres, and given ownership of it to the `gotosocial` user.
|
||||
|
||||
The psql commands to do this will look something like:
|
||||
|
||||
```psql
|
||||
create database gotosocial;
|
||||
create user gotosocial with password 'some_really_good_password';
|
||||
grant all privileges on database gotosocial to gotosocial;
|
||||
```
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
############################
|
||||
##### DATABASE CONFIG ######
|
||||
############################
|
||||
|
||||
# Config pertaining to the Gotosocial database connection
|
||||
db:
|
||||
|
||||
# String. Database type.
|
||||
# Options: ["postgres","sqlite"]
|
||||
# Default: "postgres"
|
||||
type: "postgres"
|
||||
|
||||
# String. Database address or parameters.
|
||||
# Examples: ["localhost","my.db.host","127.0.0.1","192.111.39.110",":memory:"]
|
||||
# Default: "localhost"
|
||||
address: "127.0.0.1"
|
||||
|
||||
# Int. Port for database connection.
|
||||
# Examples: [5432, 1234, 6969]
|
||||
# Default: 5432
|
||||
port: 5432
|
||||
|
||||
# String. Username for the database connection.
|
||||
# Examples: ["mydbuser","postgres","gotosocial"]
|
||||
# Default: "postgres"
|
||||
user: "postgres"
|
||||
|
||||
# REQUIRED
|
||||
# String. Password to use for the database connection
|
||||
# Examples: ["password123","verysafepassword","postgres"]
|
||||
# Default: "postgres"
|
||||
password: "postgres"
|
||||
|
||||
# String. Name of the database to use within the provided database type.
|
||||
# Examples: ["mydb","postgres","gotosocial"]
|
||||
# Default: "postgres"
|
||||
database: "postgres"
|
||||
|
||||
# String. Disable, enable, or require SSL/TLS connection to the database.
|
||||
# If "disable" then no TLS connection will be attempted.
|
||||
# If "enable" then TLS will be tried, but the database certificate won't be checked (for self-signed certs).
|
||||
# If "require" then TLS will be required to make a connection, and a valid certificate must be presented.
|
||||
# Options: ["disable", "enable", "require"]
|
||||
# Default: "disable"
|
||||
tlsMode: "disable"
|
||||
|
||||
# String. Path to a CA certificate on the host machine for db certificate validation.
|
||||
# If this is left empty, just the host certificates will be used.
|
||||
# If filled in, the certificate will be loaded and added to host certificates.
|
||||
# Examples: ["/path/to/some/cert.crt"]
|
||||
# Default: ""
|
||||
tlsCACert: ""
|
||||
```
|
||||
|
|
@ -1,3 +1,67 @@
|
|||
# General
|
||||
|
||||
TODO
|
||||
The top-level configuration for GoToSocial, including basic things like host and transport protocol.
|
||||
|
||||
The only things you *really* need to set here are `host`, which should be the hostname where your instance is reachable, and probably `port`.
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
###########################
|
||||
##### GENERAL CONFIG ######
|
||||
###########################
|
||||
|
||||
# String. Log level to use throughout the application. Must be lower-case.
|
||||
# Options: ["trace","debug","info","warn","error","fatal"]
|
||||
# Default: "info"
|
||||
logLevel: "info"
|
||||
|
||||
# String. Application name to use internally.
|
||||
# Examples: ["My Application","gotosocial"]
|
||||
# Default: "gotosocial"
|
||||
applicationName: "gotosocial"
|
||||
|
||||
# String. Hostname that this server will be reachable at. Defaults to localhost for local testing,
|
||||
# but you should *definitely* change this when running for real, or your server won't work at all.
|
||||
# DO NOT change this after your server has already run once, or you will break things!
|
||||
# Examples: ["gts.example.org","some.server.com"]
|
||||
# Default: "localhost"
|
||||
host: "localhost"
|
||||
|
||||
# String. Domain to use when federating profiles. This is useful when you want your server to be at
|
||||
# eg., "gts.example.org", but you want the domain on accounts to be "example.org" because it looks better
|
||||
# or is just shorter/easier to remember.
|
||||
# To make this setting work properly, you need to redirect requests at "example.org/.well-known/webfinger"
|
||||
# to "gts.example.org/.well-known/webfinger" so that GtS can handle them properly.
|
||||
# You should also redirect requests at "example.org/.well-known/nodeinfo" in the same way.
|
||||
# An empty string (ie., not set) means that the same value as 'host' will be used.
|
||||
# DO NOT change this after your server has already run once, or you will break things!
|
||||
# Examples: ["example.org","server.com"]
|
||||
# Default: ""
|
||||
accountDomain: ""
|
||||
|
||||
# String. Protocol to use for the server. Only change to http for local testing!
|
||||
# This should be the protocol part of the URI that your server is actually reachable on. So even if you're
|
||||
# running GoToSocial behind a reverse proxy that handles SSL certificates for you, instead of using built-in
|
||||
# letsencrypt, it should still be https.
|
||||
# Options: ["http","https"]
|
||||
# Default: "https"
|
||||
protocol: "https"
|
||||
|
||||
# Int. Listen port for the GoToSocial webserver + API. If you're running behind a reverse proxy and/or in a docker,
|
||||
# container, just set this to whatever you like (or leave the default), and make sure it's forwarded properly.
|
||||
# If you are running with built-in letsencrypt enabled, and running GoToSocial directly on a host machine, you will
|
||||
# probably want to set this to 443 (standard https port), unless you have other services already using that port.
|
||||
# This *MUST NOT* be the same as the letsencrypt port specified below, unless letsencrypt is turned off.
|
||||
# Examples: [443, 6666, 8080]
|
||||
# Default: 8080
|
||||
port: 8080
|
||||
|
||||
# Array of string. CIDRs or IP addresses of proxies that should be trusted when determining real client IP from behind a reverse proxy.
|
||||
# If you're running inside a Docker container behind Traefik or Nginx, for example, add the subnet of your docker network,
|
||||
# or the gateway of the docker network, and/or the address of the reverse proxy (if it's not running on the host network).
|
||||
# Example: ["127.0.0.1/32", "172.20.0.1"]
|
||||
# Default: ["127.0.0.1/32"] (localhost)
|
||||
trustedProxies:
|
||||
- "127.0.0.1/32"
|
||||
```
|
||||
|
|
|
|||
73
docs/configuration/index.md
Normal file
73
docs/configuration/index.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# Configuration Overview
|
||||
|
||||
GoToSocial aims to be as configurable as possible, to fit lots of different use cases.
|
||||
|
||||
We try to provide sensible defaults wherever possible, but you can't run a GoToSocial instance without managing *some* configuration.
|
||||
|
||||
In this section, we describe the different methods available for configuring GoToSocial,
|
||||
|
||||
## Configuration Methods
|
||||
|
||||
There are three different methods for configuring a GoToSocial instance, which can be combined depending on your setup.
|
||||
|
||||
### Configuration File
|
||||
|
||||
The easiest way to configure GoToSocial is to pass a configuration file to to the `gotosocial server start` command, for example:
|
||||
|
||||
```bash
|
||||
gotosocial --config-path ./config.yaml server start
|
||||
```
|
||||
|
||||
The command expects a file in [YAML](https://en.wikipedia.org/wiki/YAML) format.
|
||||
|
||||
An example configuration file, with an explanation of each of the config fields, with default and example values, can be found [here](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml).
|
||||
|
||||
This example file is included with release downloads, so you can just copy it and edit it to your needs without having to worry too much about what the hell YAML is.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
You can also configure GoToSocial by setting [environment variables](https://en.wikipedia.org/wiki/Environment_variable). These environment variables generally follow the format:
|
||||
|
||||
```text
|
||||
GTS_[CONFIG_SECTION]_[FIELD_NAME]
|
||||
```
|
||||
|
||||
So for example, instead of setting `media.maxImageSize` to `2097152` in your config.yaml, you could set the environment variable:
|
||||
|
||||
```text
|
||||
GTS_MEDIA_MAX_IMAGE_SIZE=2097152
|
||||
```
|
||||
|
||||
If you're in doubt about any of the names of these environment variables, just check `gotosocial --help`. They're all listed there.
|
||||
|
||||
### Command Line Flags
|
||||
|
||||
Finally, you can set configuration values using command-line flags, which you pass directly when you're running a `gotosocial` command. For example, instead of setting `media.maxImageSize` in your config.yaml, or with an environment variable, you can pass the value directly through the command line:
|
||||
|
||||
```bash
|
||||
gotosocial --media-max-image-size 2097152 server start
|
||||
```
|
||||
|
||||
Note the weird order of the above command; `gotosocial` first, then all global variables (like the ones in the config.yaml), then the command you want to execute.
|
||||
|
||||
If you're in doubt about which flags are available, check `gotosocial --help`.
|
||||
|
||||
## Priority
|
||||
|
||||
The above configuration methods override each other in the order in which they were listed.
|
||||
|
||||
```text
|
||||
command line flags > environment variables > config file
|
||||
```
|
||||
|
||||
That is, if you set `media.maxImageSize` to `2097152` in your config file, but then *ALSO* set the environment variable `GTS_MEDIA_MAX_IMAGE_SIZE=9999999`, then the final value will be `9999999`, because environment variables have a *higher priority* than values set in config.yaml.
|
||||
|
||||
Command line flags have the highest priority, so if you set `--media-max-image-size 13121312`, then the final value will be `13121312` regardless of what you've set elsewhere.
|
||||
|
||||
This means in cases where you want to just try changing one thing, but don't want to edit your config file, you can temporarily use an environment variable or a command line flag to set that one thing.
|
||||
|
||||
## Default Values
|
||||
|
||||
Reasonable default values are provided for *most* of the configuration parameters, except in cases where a custom value is absolutely required.
|
||||
|
||||
See the [example config file](https://github.com/superseriousbusiness/gotosocial/blob/main/example/config.yaml) for the default values, or run `gotosocial --help`.
|
||||
43
docs/configuration/letsencrypt.md
Normal file
43
docs/configuration/letsencrypt.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
# LetsEncrypt
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
##############################
|
||||
##### LETSENCRYPT CONFIG #####
|
||||
##############################
|
||||
|
||||
# Config pertaining to the automatic acquisition and use of LetsEncrypt HTTPS certificates.
|
||||
letsEncrypt:
|
||||
|
||||
# Bool. Whether or not letsencrypt should be enabled for the server.
|
||||
# If false, the rest of the settings here will be ignored.
|
||||
# You should only change this if you want to serve GoToSocial behind a reverse proxy
|
||||
# like Traefik, HAProxy, or Nginx.
|
||||
# Options: [true, false]
|
||||
# Default: true
|
||||
enabled: true
|
||||
|
||||
# Int. Port to listen for letsencrypt certificate challenges on.
|
||||
# If letsencrypt is enabled, this port must be reachable or you won't be able to obtain certs.
|
||||
# If letsencrypt is disabled, this port will not be used.
|
||||
# This *must not* be the same as the webserver/API port specified above.
|
||||
# Examples: [80, 8000, 1312]
|
||||
# Default: 80
|
||||
port: 80
|
||||
|
||||
# String. Directory in which to store LetsEncrypt certificates.
|
||||
# It is a good move to make this a sub-path within your storage directory, as it makes
|
||||
# backup easier, but you might wish to move them elsewhere if they're also accessed by other services.
|
||||
# In any case, make sure GoToSocial has permissions to write to / read from this directory.
|
||||
# Examples: ["/home/gotosocial/storage/certs", "/acmecerts"]
|
||||
# Default: "/gotosocial/storage/certs"
|
||||
certDir: "/gotosocial/storage/certs"
|
||||
|
||||
# String. Email address to use when registering LetsEncrypt certs.
|
||||
# Most likely, this will be the email address of the instance administrator.
|
||||
# LetsEncrypt will send notifications about expiring certificates etc to this address.
|
||||
# Examples: ["admin@example.org"]
|
||||
# Default: ""
|
||||
emailAddress: ""
|
||||
```
|
||||
32
docs/configuration/media.md
Normal file
32
docs/configuration/media.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
# Media
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
########################
|
||||
##### MEDIA CONFIG #####
|
||||
########################
|
||||
|
||||
# Config pertaining to user media uploads (videos, image, image descriptions).
|
||||
media:
|
||||
|
||||
# Int. Maximum allowed image upload size in bytes.
|
||||
# Examples: [2097152, 10485760]
|
||||
# Default: 2097152 -- aka 2MB
|
||||
maxImageSize: 2097152
|
||||
|
||||
# Int. Maximum allowed video upload size in bytes.
|
||||
# Examples: [2097152, 10485760]
|
||||
# Default: 10485760 -- aka 10MB
|
||||
maxVideoSize: 10485760
|
||||
|
||||
# Int. Minimum amount of characters required as an image or video description.
|
||||
# Examples: [500, 1000, 1500]
|
||||
# Default: 0 (not required)
|
||||
minDescriptionChars: 0
|
||||
|
||||
# Int. Maximum amount of characters permitted in an image or video description.
|
||||
# Examples: [500, 1000, 1500]
|
||||
# Default: 500
|
||||
maxDescriptionChars: 500
|
||||
```
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# Overview
|
||||
|
||||
TODO
|
||||
45
docs/configuration/statuses.md
Normal file
45
docs/configuration/statuses.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Statuses
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
##########################
|
||||
##### STORAGE CONFIG #####
|
||||
##########################
|
||||
|
||||
# Config pertaining to storage of user-created uploads (videos, images, etc).
|
||||
storage:
|
||||
|
||||
# String. Type of storage backend to use.
|
||||
# Examples: ["local", "s3"]
|
||||
# Default: "local" (storage on local disk)
|
||||
# NOTE: s3 storage is not yet supported!
|
||||
backend: "local"
|
||||
|
||||
# String. Directory to use as a base path for storing files.
|
||||
# Make sure whatever user/group gotosocial is running as has permission to access
|
||||
# this directly, and create new subdirectories and files with in.
|
||||
# Examples: ["/home/gotosocial/storage", "/opt/gotosocial/datastorage"]
|
||||
# Default: "/gotosocial/storage"
|
||||
basePath: "/gotosocial/storage"
|
||||
|
||||
# String. Protocol to use for serving stored files.
|
||||
# It's very unlikely that you'll need to change this ever, but there might be edge cases.
|
||||
# Examples: ["http", "https"]
|
||||
serveProtocol: "https"
|
||||
|
||||
# String. Host for serving stored files.
|
||||
# If you're using local storage, this should be THE SAME as the value you've set for Host, above.
|
||||
# It should only be a different value if you're serving stored files from a host
|
||||
# other than the one your instance is running on.
|
||||
# Examples: ["localhost", "example.org"]
|
||||
# Default: "localhost" -- you should absolutely change this.
|
||||
serveHost: "localhost"
|
||||
|
||||
# String. Base path for serving stored files. This will be added to serveHost and serveProtocol
|
||||
# to form the prefix url of your stored files. Eg., https://example.org/fileserver/.....
|
||||
# It's unlikely that you will need to change this.
|
||||
# Examples: ["/fileserver", "/media"]
|
||||
# Default: "/fileserver"
|
||||
serveBasePath: "/fileserver"
|
||||
```
|
||||
45
docs/configuration/storage.md
Normal file
45
docs/configuration/storage.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Storage
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
##########################
|
||||
##### STORAGE CONFIG #####
|
||||
##########################
|
||||
|
||||
# Config pertaining to storage of user-created uploads (videos, images, etc).
|
||||
storage:
|
||||
|
||||
# String. Type of storage backend to use.
|
||||
# Examples: ["local", "s3"]
|
||||
# Default: "local" (storage on local disk)
|
||||
# NOTE: s3 storage is not yet supported!
|
||||
backend: "local"
|
||||
|
||||
# String. Directory to use as a base path for storing files.
|
||||
# Make sure whatever user/group gotosocial is running as has permission to access
|
||||
# this directly, and create new subdirectories and files with in.
|
||||
# Examples: ["/home/gotosocial/storage", "/opt/gotosocial/datastorage"]
|
||||
# Default: "/gotosocial/storage"
|
||||
basePath: "/gotosocial/storage"
|
||||
|
||||
# String. Protocol to use for serving stored files.
|
||||
# It's very unlikely that you'll need to change this ever, but there might be edge cases.
|
||||
# Examples: ["http", "https"]
|
||||
serveProtocol: "https"
|
||||
|
||||
# String. Host for serving stored files.
|
||||
# If you're using local storage, this should be THE SAME as the value you've set for Host, above.
|
||||
# It should only be a different value if you're serving stored files from a host
|
||||
# other than the one your instance is running on.
|
||||
# Examples: ["localhost", "example.org"]
|
||||
# Default: "localhost" -- you should absolutely change this.
|
||||
serveHost: "localhost"
|
||||
|
||||
# String. Base path for serving stored files. This will be added to serveHost and serveProtocol
|
||||
# to form the prefix url of your stored files. Eg., https://example.org/fileserver/.....
|
||||
# It's unlikely that you will need to change this.
|
||||
# Examples: ["/fileserver", "/media"]
|
||||
# Default: "/fileserver"
|
||||
serveBasePath: "/fileserver"
|
||||
```
|
||||
22
docs/configuration/template.md
Normal file
22
docs/configuration/template.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Template
|
||||
|
||||
## Settings
|
||||
|
||||
```yaml
|
||||
###############################
|
||||
##### WEB TEMPLATE CONFIG #####
|
||||
###############################
|
||||
|
||||
# Config pertaining to templating of web pages/email notifications and the like
|
||||
template:
|
||||
|
||||
# String. Directory from which gotosocial will attempt to load html templates (.tmpl files).
|
||||
# Examples: ["/some/absolute/path/", "./relative/path/", "../../some/weird/path/"]
|
||||
# Default: "./web/template/"
|
||||
baseDir: "./web/template/"
|
||||
|
||||
# String. Directory from which gotosocial will attempt to serve static web assets (images, scripts).
|
||||
# Examples: ["/some/absolute/path/", "./relative/path/", "../../some/weird/path/"]
|
||||
# Default: "./web/assets/"
|
||||
assetBaseDir: "./web/assets/"
|
||||
```
|
||||
45
docs/environment.yml
Normal file
45
docs/environment.yml
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
name: gotosocial-docs
|
||||
channels:
|
||||
- defaults
|
||||
dependencies:
|
||||
- _libgcc_mutex=0.1=main
|
||||
- _openmp_mutex=4.5=1_gnu
|
||||
- bzip2=1.0.8=h7b6447c_0
|
||||
- ca-certificates=2021.10.26=h06a4308_2
|
||||
- certifi=2020.6.20=pyhd3eb1b0_3
|
||||
- ld_impl_linux-64=2.35.1=h7274673_9
|
||||
- libffi=3.3=he6710b0_2
|
||||
- libgcc-ng=9.3.0=h5101ec6_17
|
||||
- libgomp=9.3.0=h5101ec6_17
|
||||
- libstdcxx-ng=9.3.0=hd4cf53a_17
|
||||
- libuuid=1.0.3=h7f8727e_2
|
||||
- ncurses=6.3=h7f8727e_2
|
||||
- openssl=1.1.1l=h7f8727e_0
|
||||
- python=3.10.0=h151d27f_3
|
||||
- readline=8.1=h27cfd23_0
|
||||
- sqlite=3.36.0=hc218d9a_0
|
||||
- tk=8.6.11=h1ccaba5_0
|
||||
- tzdata=2021e=hda174b7_0
|
||||
- wheel=0.37.0=pyhd3eb1b0_1
|
||||
- xz=5.2.5=h7b6447c_0
|
||||
- zlib=1.2.11=h7b6447c_3
|
||||
- pip:
|
||||
- click==8.0.3
|
||||
- ghp-import==2.0.2
|
||||
- importlib-metadata==4.8.2
|
||||
- jinja2==3.0.3
|
||||
- markdown==3.3.4
|
||||
- markupsafe==2.0.1
|
||||
- mergedeep==1.3.4
|
||||
- mkdocs==1.2.3
|
||||
- mkdocs-render-swagger-plugin==0.0.3
|
||||
- packaging==21.2
|
||||
- pip==21.2.4
|
||||
- pyparsing==2.4.7
|
||||
- python-dateutil==2.8.2
|
||||
- pyyaml==6.0
|
||||
- pyyaml-env-tag==0.1
|
||||
- setuptools==58.0.4
|
||||
- six==1.16.0
|
||||
- watchdog==2.1.6
|
||||
- zipp==3.6.0
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
# Glossary
|
||||
|
||||
Some commonly-used terms in discussions of federation, and their meanings.
|
||||
|
||||
### `ActivityPub`
|
||||
|
||||
A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
|
||||
|
||||
GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
|
||||
|
||||
### `ActivityStreams`
|
||||
|
||||
A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
|
||||
|
||||
GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
|
||||
|
||||
### `Actor`
|
||||
|
||||
An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
|
||||
|
||||
In GoToSocial, each account/user is an actor.
|
||||
|
||||
### `Dereference`
|
||||
|
||||
To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
|
||||
|
||||
GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.
|
||||
39
docs/federation/index.md
Normal file
39
docs/federation/index.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# Why Federation?
|
||||
|
||||
GoToSocial uses the [ActivityPub](https://activitypub.rocks/) federation protocol.
|
||||
|
||||
Federation means that you can hang out not just with people on your home server, but with people all over the [Fediverse](https://en.wikipedia.org/wiki/Fediverse). Your home server is part of a network of servers all over the world that all communicate using the same protocol--they speak the same 'language'. Your data is no longer centralized on one company's servers, but resides on your own server and is shared -- as you see fit -- across a resilient web of servers run by other people.
|
||||
|
||||
Not all of the servers you 'federate' with will be running GoToSocial: popular implementations of ActivityPub include software like [Mastodon](https://joinmastodon.org/), [WriteFreely](https://writefreely.org/), and many others. GoToSocial communicates seamlessly with these other servers. To take a corporate
|
||||
|
||||
This federated approach also means that you aren't beholden to arbitrary rules from some gigantic corporation potentially thousands of miles away. Your server has its own rules and culture; your fellow server residents are your neighbors; you will likely get to know your server admins and moderators, or be an admin yourself.
|
||||
|
||||
GoToSocial advocates for many small, weird, specialist servers where people can feel at home, rather than a few big and generic ones where one person's voice can get lost in the crowd.
|
||||
|
||||
## Glossary
|
||||
|
||||
Some commonly-used terms in discussions of federation, and their meanings.
|
||||
|
||||
### `ActivityPub`
|
||||
|
||||
A decentralized social networking protocol based on the ActivityStreams data format. See [here](https://www.w3.org/TR/activitypub/).
|
||||
|
||||
GoToSocial uses the ActivityPub protocol to communicate between GtS servers, and with other federated servers like Mastodon, Pixelfed, etc.
|
||||
|
||||
### `ActivityStreams`
|
||||
|
||||
A model/data format for representing potential and completed activities using JSON. See [here](https://www.w3.org/TR/activitystreams-core/).
|
||||
|
||||
GoToSocial uses the ActivityStreams data model to 'speak' ActivityPub with other servers.
|
||||
|
||||
### `Actor`
|
||||
|
||||
An actor is an ActivityStreams object that is capable of performing some Activity like following, liking, creating a post, reblogging, etc. See [here](https://www.w3.org/TR/activitypub/#actors).
|
||||
|
||||
In GoToSocial, each account/user is an actor.
|
||||
|
||||
### `Dereference`
|
||||
|
||||
To 'dereference' a post or a profile means to make an HTTP call to the server that hosts that post or profile, in order to obtain its ActivityStreams representation.
|
||||
|
||||
GoToSocial 'dereferences' posts and profiles on remote servers, in order to convert them to models that GoToSocial can understand and work with.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
# Principles
|
||||
|
||||
TODO -- describe the principles GtS uses for federating.
|
||||
|
||||
Eg:
|
||||
|
||||
* Why federate?
|
||||
* Why ActivityPub?
|
||||
* Broad overview of how GtS fits into the fediverse.
|
||||
143
docs/index.md
143
docs/index.md
|
|
@ -1,7 +1,5 @@
|
|||
# What is GoToSocial?
|
||||
|
||||
 
|
||||
|
||||
GoToSocial is an [ActivityPub](https://activitypub.rocks/) social network server, written in Golang.
|
||||
|
||||
With GoToSocial, you can keep in touch with your friends, post, read, and share images and articles. All without being tracked or advertised to!
|
||||
|
|
@ -20,110 +18,12 @@ GoToSocial is not designed for 'must-follow' influencers with tens of thousands
|
|||
|
||||
GoToSocial doesn't claim to be *better* than any other application, but it offers something that might better *for you* in particular.
|
||||
|
||||
### Federation
|
||||
|
||||
Because GoToSocial uses [ActivityPub](https://activitypub.rocks/), you can hang out not just with people on your home server, but with people all over the [Fediverse](https://en.wikipedia.org/wiki/Fediverse), seamlessly.
|
||||
|
||||
Federation means that your home server is part of a network of servers all over the world that all communicate using the same protocol. Your data is no longer centralized on one company's servers, but resides on your own server and is shared -- as you see fit -- across a resilient web of servers run by other people.
|
||||
|
||||
This federated approach also means that you aren't beholden to arbitrary rules from some gigantic corporation potentially thousands of miles away. Your server has its own rules and culture; your fellow server residents are your neighbors; you will likely get to know your server admins and moderators, or be an admin yourself.
|
||||
|
||||
GoToSocial advocates for many small, weird, specialist servers where people can feel at home, rather than a few big and generic ones where one person's voice can get lost in the crowd.
|
||||
|
||||
### History and Status
|
||||
## History and Status
|
||||
|
||||
This project sprang up in 2021 out of a dissatisfaction with the safety + privacy features of other Federated microblogging/social media applications, and a desire to implement something a little different.
|
||||
|
||||
It began as a solo project, and then picked up steam as more developers became interested and jumped on.
|
||||
|
||||
The project is still in prerelease, but is already deployable and very useable, and it federates cleanly with most other Fediverse servers (not yet all).
|
||||
|
||||
## Features
|
||||
|
||||
### Mastodon API compatibility
|
||||
|
||||
The Mastodon API has become the de-facto standard for client communication with federated servers, so GoToSocial has implemented and extended the API with custom functionality.
|
||||
|
||||
In short this means full support for modern, beautiful apps like [Tusky](https://tusky.app/) and [Pinafore](https://pinafore.social/).
|
||||
|
||||
| Tusky | Pinafore |
|
||||
| :----------------------------------------------------: | :----------------------------------------------------------: |
|
||||
|  |  |
|
||||
|
||||
If you're used to using Mastodon with Tusky or Pinafore, you'll find using GoToSocial a breeze.
|
||||
|
||||
### Granular post settings
|
||||
|
||||
It's important that when you post something, you can choose who sees it.
|
||||
|
||||
GoToSocial offers public/unlisted/friends-only/mutuals-only/and direct posts (slide in DMs! -- with consent).
|
||||
|
||||
It also allows you to customize how people interact with your posts:
|
||||
|
||||
- Local-only posts.
|
||||
- Rebloggable/boostable toggle.
|
||||
- 'Likeable' toggle.
|
||||
- 'Replyable' toggle.
|
||||
|
||||
### Customizability for admins
|
||||
|
||||
Lots of config options for admins to play around with, including:
|
||||
|
||||
- Easily-adjustable post length.
|
||||
- Media upload size settings.
|
||||
|
||||
### Easy to run
|
||||
|
||||
No external dependencies apart from a database (or just use SQLite!). Simply download the binary + assets (or Docker container), and run.
|
||||
|
||||
GoToSocial plays nice with lower-powered machines like Raspberry Pi, old laptops and tiny $5/month VPSes.
|
||||
|
||||
### Safety + security features
|
||||
|
||||
- Built-in, automatic support for secure HTTPS with [LetsEncrypt](https://letsencrypt.org/).
|
||||
- Strict privacy enforcement for posts and strict blocking logic.
|
||||
- Import and export allowlists and denylists. Subscribe to community-created blocklists (think Adblocker, but for federation!).
|
||||
- HTTP signature authentication: GoToSocial requires [HTTP Signatures](https://tools.ietf.org/id/draft-cavage-http-signatures-01.html) when sending and receiving messages, to ensure that your messages can't be tampered with and your identity can't be forged.
|
||||
|
||||
### Various federation modes
|
||||
|
||||
GoToSocial doesn't apply a one-size-fits-all approach to federation. Who your server federates with should be up to you.
|
||||
|
||||
- 'Normal' federation; discover new servers.
|
||||
- Allowlist-only federation; choose which servers you talk to.
|
||||
- Zero federation; keep your server private.
|
||||
|
||||
### OIDC integration
|
||||
|
||||
GoToSocial supports [OpenID Connect (OIDC)](https://openid.net/connect/) identity providers, meaning you can integrate it with existing user management services like [Auth0](https://auth0.com/), [Gitlab](https://docs.gitlab.com/ee/integration/openid_connect_provider.html), etc, or run your own and hook GtS up to that (we recommend [Dex](https://dexidp.io/)).
|
||||
|
||||
### Backend-first design
|
||||
|
||||
Unlike other federated server projects, GoToSocial doesn't include an integrated client front-end (ie., a webapp).
|
||||
|
||||
Instead, like Matrix.org's [Synapse](https://github.com/matrix-org/synapse) project, it provides a relatively generic backend server implementation, some beautiful static pages for profiles and posts, and a [well-documented API](https://docs.gotosocial.org/en/latest/api/swagger/).
|
||||
|
||||
On top of this API, web developers are encouraged to build any front-end implementation or mobile application that they wish, whether Tumblr-like, Facebook-like, Twitter-like, or something else entirely.
|
||||
|
||||
## Wishlist
|
||||
|
||||
These cool things will be implemented if time allows (because we really want them):
|
||||
|
||||
- **Groups** and group posting!
|
||||
- Reputation-based 'slow' federation.
|
||||
- Community decision making for federation and moderation actions.
|
||||
- User-selectable custom templates for rendering public posts:
|
||||
- Twitter-style
|
||||
- Blogpost
|
||||
- Gallery
|
||||
- Etc.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Proper documentation for running and maintaining GoToSocial will be forthcoming in the first release.
|
||||
|
||||
For now (if you want to run it pre-alpha, like a beast), check out the [quick and dirty getting started guide](https://docs.gotosocial.org/en/latest/installation_guide/quick_and_dirty/).
|
||||
|
||||
## Contributing
|
||||
|
||||
You wanna contribute to GtS? Great! ❤️❤️❤️ Check out the issues page to see if there's anything you wanna jump in on, and read the CONTRIBUTING.md file on the repository for guidelines and setting up your dev environment.
|
||||
|
|
@ -136,46 +36,9 @@ For bugs and feature requests, please check to see if there's [already an issue]
|
|||
|
||||
## Credits
|
||||
|
||||
### Libraries
|
||||
|
||||
The following libraries and frameworks are used by GoToSocial, with gratitude 💕
|
||||
|
||||
- [buckket/go-blurhash](https://github.com/buckket/go-blurhash); used for generating image blurhashes. [GPL-3.0 License](https://spdx.org/licenses/GPL-3.0-only.html).
|
||||
- [coreos/go-oidc](https://github.com/coreos/go-oidc); OIDC client library. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html).
|
||||
- [gin-gonic/gin](https://github.com/gin-gonic/gin); speedy router engine. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [gin-contrib/cors](https://github.com/gin-contrib/cors); Gin CORS middleware. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [gin-contrib/sessions](https://github.com/gin-contrib/sessions); Gin sessions middleware. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [gin-contrib/static](https://github.com/gin-contrib/static); Gin static page middleware. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [go-fed/activity](https://github.com/go-fed/activity); Golang ActivityPub/ActivityStreams library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [go-fed/httpsig](https://github.com/go-fed/httpsig); secure HTTP signature library. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [google/uuid](https://github.com/google/uuid); UUID generation. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html)
|
||||
- [go-playground/validator](https://github.com/go-playground/validator); struct validation. [MIT License](https://spdx.org/licenses/MIT.html)
|
||||
- [gorilla/websocket](https://github.com/gorilla/websocket); Websocket connectivity. [BSD-2-Clause License](https://spdx.org/licenses/BSD-2-Clause.html).
|
||||
- [h2non/filetype](https://github.com/h2non/filetype); filetype checking. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [jackc/pgx](https://github.com/jackc/pgx); Postgres driver. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [microcosm-cc/bluemonday](https://github.com/microcosm-cc/bluemonday); HTML user-input sanitization. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [mitchellh/mapstructure](https://github.com/mitchellh/mapstructure); Go interface => struct parsing. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [modernc.org/sqlite](https://gitlab.com/cznic/sqlite); cgo-free port of SQLite. [Other License](https://gitlab.com/cznic/sqlite/-/blob/master/LICENSE).
|
||||
- [modernc.org/ccgo](https://gitlab.com/cznic/ccgo); c99 AST -> Go translater. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [modernc.org/libc](https://gitlab.com/cznic/libc); C-runtime services. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [mvdan/xurls](https://github.com/mvdan/xurls); URL parsing regular expressions. [BSD-3-Clause License](https://spdx.org/licenses/BSD-3-Clause.html).
|
||||
- [nfnt/resize](https://github.com/nfnt/resize); convenient image resizing. [ISC License](https://spdx.org/licenses/ISC.html).
|
||||
- [oklog/ulid](https://github.com/oklog/ulid); sequential, database-friendly ID generation. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html).
|
||||
- [ReneKroon/ttlcache](https://github.com/ReneKroon/ttlcache); in-memory caching. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [russross/blackfriday](https://github.com/russross/blackfriday); markdown parsing for statuses. [Simplified BSD License](https://spdx.org/licenses/BSD-2-Clause.html).
|
||||
- [sirupsen/logrus](https://github.com/sirupsen/logrus); logging. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [stretchr/testify](https://github.com/stretchr/testify); test framework. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [superseriousbusiness/exifremove](https://github.com/superseriousbusiness/exifremove) forked from [scottleedavis/go-exif-remove](https://github.com/scottleedavis/go-exif-remove); EXIF data removal. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [superseriousbusiness/oauth2](https://github.com/superseriousbusiness/oauth2) forked from [go-oauth2/oauth2](https://github.com/go-oauth2/oauth2); oauth server framework and token handling. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [go-swagger/go-swagger](https://github.com/go-swagger/go-swagger); Swagger OpenAPI spec generation. [Apache-2.0 License](https://spdx.org/licenses/Apache-2.0.html).
|
||||
- [tdewolff/minify](https://github.com/tdewolff/minify); HTML minification. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [uptrace/bun](https://github.com/uptrace/bun); database ORM. [BSD-2-Clause License](https://spdx.org/licenses/BSD-2-Clause.html).
|
||||
- [urfave/cli](https://github.com/urfave/cli); command-line interface framework. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
- [wagslane/go-password-validator](https://github.com/wagslane/go-password-validator); password strength validation. [MIT License](https://spdx.org/licenses/MIT.html).
|
||||
|
||||
### Image Attribution
|
||||
|
||||
Sloth logo made by [Freepik](https://www.freepik.com) from [www.flaticon.com](https://www.flaticon.com/).
|
||||
Sloth logo by [Anna Abramek](https://abramek.art/), Copyright (C) 2021 the GoToSocial Authors.
|
||||
|
||||
### Developers
|
||||
|
||||
|
|
@ -187,6 +50,8 @@ In alphabetical order:
|
|||
|
||||
### Special Thanks
|
||||
|
||||
A huge thank you to CJ from [go-fed](https://github.com/go-fed/activity): without your work GoToSocial would not have been possible.
|
||||
|
||||
Thanks to everyone who has used GtS, opened an issue, suggested something, given funding, and otherwise encouraged or supported the project!
|
||||
|
||||
## Sponsorship + Funding
|
||||
|
|
|
|||
|
|
@ -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
31
docs/installation_guide/index.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
33
mkdocs.yml
33
mkdocs.yml
|
|
@ -10,3 +10,36 @@ extra_javascript:
|
|||
|
||||
extra_css:
|
||||
- assets/css/swagger-ui.css
|
||||
|
||||
nav:
|
||||
- "Home": "index.md"
|
||||
- "Installation Guide":
|
||||
- "installation_guide/index.md"
|
||||
- "installation_guide/binary.md"
|
||||
- "installation_guide/docker.md"
|
||||
- "Configuration":
|
||||
- "configuration/index.md"
|
||||
- "configuration/general.md"
|
||||
- "configuration/database.md"
|
||||
- "configuration/template.md"
|
||||
- "configuration/accounts.md"
|
||||
- "configuration/media.md"
|
||||
- "configuration/storage.md"
|
||||
- "configuration/statuses.md"
|
||||
- "configuration/letsencrypt.md"
|
||||
- "configuration/oidc.md"
|
||||
- "configuration/smtp.md"
|
||||
- "Admin":
|
||||
- "admin/admin_panel.md"
|
||||
- "admin/cli.md"
|
||||
- "admin/backup_and_restore.md"
|
||||
- "User Guide":
|
||||
- "user_guide/posts.md"
|
||||
- "user_guide/password_management.md"
|
||||
- "Federation":
|
||||
- "federation/index.md"
|
||||
- "federation/security.md"
|
||||
- "federation/behaviors/outbox.md"
|
||||
- "federation/behaviors/conversation_threads.md"
|
||||
- "API Documentation":
|
||||
- "api/swagger.md"
|
||||
|
|
|
|||
Loading…
Reference in a new issue