* move scripts, allow testing both dbs with one cmd
* tidy + vendor
* update test.sh to ignore cache
* put test commands directly in drone.yml
* change CONTRIBUTING slightly
* go ham on the readme
Before starting on something, please comment on an issue to say that you're working on it, and/or drop into the GoToSocial Matrix room [here](https://matrix.to/#/#gotosocial:superseriousbusiness.org).
@ -28,7 +46,7 @@ To get started, you first need to have Go installed. GtS is currently using Go 1
Once you've got go installed, clone this repository into your Go path. Normally, this should be `~/go/src/github.com/superseriousbusiness/gotosocial`.
Once that's done, you can try building the project: `./build.sh`. This will build the `gotosocial` binary.
Once that's done, you can try building the project: `./scripts/build.sh`. This will build the `gotosocial` binary.
If there are no errors, great, you're good to go!
@ -76,12 +94,12 @@ One thing that *isn't* mocked is the Database interface, because it's just easie
You can also launch a testrig as a standalone server running at localhost, which you can connect to using something like [Pinafore](https://github.com/nolanlawson/pinafore).
To do this, first build the gotosocial binary with `./build.sh`.
To do this, first build the gotosocial binary with `./scripts/build.sh`.
Then, launch the testrig by invoking the binary as follows:
To run Pinafore locally in dev mode, first clone the Pinafore repository, and run the following command in the cloned directory:
@ -104,13 +122,33 @@ Note the following constraints:
## Running tests
Because the tests use a real SQLite database under the hood, you can't run them in parallel, so you need to run tests with the following command:
There are a few different ways of running tests. Each requires the use of the `-p 1` flag, to indicate that they should not be run in parallel.
### SQLite
If you want to run tests as quickly as possible, using an SQLite in-memory database, use:
```bash
go test -p 1 ./...
GTS_DB_TYPE="sqlite" GTS_DB_ADDRESS=":memory:" go test -p 1 ./...
```
The `-p 1` flag means that only 1 test will be run at a time.
### Postgres
If you want to run tests against a Postgres database running on localhost, run:
```bash
GTS_DB_TYPE="postgres" GTS_DB_ADDRESS="localhost" go test -p 1 ./...
```
In the above command, it is assumed you are using the default Postgres password of `postgres`.
### Both
Finally, to run tests against both database types one after the other, use:
```bash
./scripts/test.sh
```
## Linting
@ -140,6 +178,44 @@ golint ./internal/...
Then make sure to run `go fmt ./...` to update whitespace and other opinionated formatting.
## Updating Swagger docs
If you change swagger annotations on any of the API paths, you need to generate a new swagger file at `./docs/api/swagger.yaml`. You can do this with:
`./scripts/generateswagger.sh`
## Pushing to Docker
You can easily build a Docker container tagged with the current branch name using:
```bash
./scripts/dockerbuild.sh
```
Then, (assuming you have permissions to push to the [GoToSocial Docker repository](https://hub.docker.com/r/superseriousbusiness/gotosocial)), run:
```bash
./scripts/dockerpush.sh
```
Note: you should never manually push a Docker container from your machine to `latest` -- we have a CI/CD flow for that. Only push a Docker container manually when you're testing changes on a branch!
## CI/CD configuration
GoToSocial uses [Drone](https://www.drone.io/) for CI/CD tasks like running tests, linting, and building Docker containers. These runs are integrated with Github, and will be run on opening a pull request or merging into main.
The Drone instance for GoToSocial is [here](https://drone.superseriousbusiness.org/superseriousbusiness/gotosocial).
The `drone.yml` file is [here](./.drone.yml) -- this defines how and when Drone should run. Documentation for Drone is [here](https://docs.drone.io/).
Please note that the `drone.yml` file must be signed by the Drone admin account in order to be considered valid. This must be done every time the file is changed. This is to prevent tampering and hijacking of the Drone instance. See [here](https://docs.drone.io/signature/).
To sign the file, first install and setup the [drone cli tool](https://docs.drone.io/cli/install/). Then, run:
Right now there's no structure in place for financial compensation for pull requests and code. This is simply because there's no money being made on the project apart from the very small weekly Liberapay donations.
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!
<palign="middle">
<imgsrc="./docs/assets/sloth.png"width="300"/>
</p>
Documentation is at [docs.gotosocial.org](https://docs.gotosocial.org). You can skip straight to the API documentation [here](https://docs.gotosocial.org/en/latest/api/swagger/).
## Table of Contents <!-- omit in toc -->
- [What is GoToSocial?](#what-is-gotosocial)
- [Federation](#federation)
- [History and Status](#history-and-status)
- [Features](#features)
- [Mastodon API compatibility](#mastodon-api-compatibility)
- [Granular post settings](#granular-post-settings)
- [Customizability for admins](#customizability-for-admins)
GoToSocial provides a lightweight, customizable, and safety-focused entryway into the [Fediverse](https://en.wikipedia.org/wiki/Fediverse), and is comparable to (but distinct from) existing projects such as [Mastodon](https://joinmastodon.org/), [Pleroma](https://pleroma.social/), [Friendica](https://friendica.net), and [PixelFed](https://pixelfed.org/).
With GoToSocial, you can keep in touch with your friends, post, read, and share images and articles, without being tracked or advertised to.
If you've ever used something like Twitter or Tumblr (or even Myspace!) GoToSocial will probably feel familiar to you: You can follow people and have followers, you make posts which people can favourite and reply to and share, and you scroll through posts from people you follow using a timeline. You can write long posts or short posts, or just post images, it's up to you. You can also, of course, block people or otherwise limit interactions that you don't want by posting just to your friends.
Documentation is at [docs.gotosocial.org](https://docs.gotosocial.org). You can skip straight to the API documentation [here](https://docs.gotosocial.org/en/latest/api/swagger/).
**GoToSocial does NOT use algorithms or collect data about you to suggest content or 'improve your experience'**. The timeline is chronological: whatever you see at the top of your timeline is there because it's *just been posted*, not because it's been selected as interesting (or controversial) based on your personal profile.
## Features
GoToSocial is not designed for 'must-follow' influencers with tens of thousands of followers, and it's not designed to be addictive. Your timeline and your experience is shaped by who you follow and how you interact with people, not by metrics of engagement!
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 the [ActivityPub](https://activitypub.rocks/) protocol, 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.
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.
### Mastodon API compatible
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.
Full support for modern, elegant apps like [Tusky](https://tusky.app/) and [Pinafore](https://pinafore.social/).
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.
### Granular post settings
### History and Status
You should be able to choose how your posts can be interacted with:
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.
* Local-only posts.
* Rebloggable/boostable toggle.
* 'Likeable' toggle.
* 'Replyable' toggle.
It began as a solo project, and then picked up steam as more developers became interested and jumped on.
### Easy customizability for admins
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).
* Adjustable post length.
* Media upload size settings.
For a detailed view on what's implemented and what's not, and progress made towards a first v0.1.0 (beta) release, see [here](./PROGRESS.md).
### LetsEncrypt
## Features
Built-in, automatic support for secure HTTPS with [LetsEncrypt](https://letsencrypt.org/).
### Mastodon API compatibility
### Light footprint and good performance
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.
Plays nice with lower-powered machines like Raspberry Pi, old laptops and tiny VPSes.
In short this means full support for modern, beautiful apps like [Tusky](https://tusky.app/) and [Pinafore](https://pinafore.social/).
 | 
No external dependencies apart from a database. Just download the binary + assets (or Docker container), and run.
If you're used to using Mastodon with Tusky or Pinafore, you'll find using GoToSocial a breeze.
### HTTP signature authentication
### Granular post settings
Protect your data.
It's important that when you post something, you can choose who sees it.
### User Safety
GoToSocial offers public/unlisted/friends-only/mutuals-only/and direct posts (slide in DMs! -- with consent).
Strict privacy enforcement for posts and strict blocking logic.
It also allows you to customize how people interact with your posts:
### Subscribeable and shareable allow/denylists for federation
- Local-only posts.
- Rebloggable/boostable toggle.
- 'Likeable' toggle.
- 'Replyable' toggle.
Import and export allowlists and denylists. Subscribe to community-created blocklists (think Adblocker, but for federation!).
### Customizability for admins
### Various federation modes
Lots of [config options](./example/config.yaml) for admins to play around with, including:
* 'Normal' federation; discover new servers.
* Allowlist-only federation; choose which servers you talk to.
* Zero federation; keep your server private.
- Easily-adjustable post length.
- Media upload size settings.
### Wishlist
### Easy to run
These cool things will be implemented if time allows (because we really want them):
No external dependencies apart from a database (or just use SQLite!). Simply download the binary + assets (or Docker container), and run.
* **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.
GoToSocial plays nice with lower-powered machines like Raspberry Pi, old laptops and tiny $5/month VPSes.
## Design Ethos
### Safety + security features
One of the key differences between GoToSocial and other federated server projects is that GoToSocial doesn't include an integrated client front-end (ie., a webapp).
- 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.
Instead, like Matrix.org's [Synapse](https://github.com/matrix-org/synapse) project, it provides only a server implementation, some static pages, and a well-documented API. On top of this API, developers are free to build any front-end implementation or mobile application that they wish.
### Various federation modes
Because the server implementation is as generic and flexible/configurable as possible, GoToSocial provides the basis for many different types of social media experience, whether Tumblr-like, Facebook-like, or Twitter-like.
GoToSocial doesn't apply a one-size-fits-all approach to federation. Who your server federates with should be up to you.
## Status
- 'Normal' federation; discover new servers.
- Allowlist-only federation; choose which servers you talk to.
- Zero federation; keep your server private.
Work began on the project around February 2021, and the project is still in prerelease.
### OIDC integration
At this point, GoToSocial is already deployable and very useable, and it federates cleanly with most other Fediverse servers (not yet all).
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/)).
For a detailed view on what's implemented and what's not, and progress made towards a first v0.1.0 (beta) release, see [here](./PROGRESS.md).
### 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
@ -119,53 +168,77 @@ 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).
* [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).
* [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).
- [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).
- [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).
- [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).
Sloth logo made by [Freepik](https://www.freepik.com) from [www.flaticon.com](https://www.flaticon.com/).
### Developers
In alphabetical order:
- f0x
- kim
- tobi
### Special Thanks
Thanks to everyone who has used GtS, opened an issue, suggested something, given funding, or otherwise encouraged or supported the project!
## Sponsorship + Funding
Currently, this project is funded using Liberapay, to put bread on the table while work continues on it.
If you want to sponsor this project, you can do so [here](https://liberapay.com/dumpsterqueer/)! `<3`
**GoToSocial has NO CORPORATE SPONSORS and does not desire corporate sponsorship.**
## License
GoToSocial is licensed under the [GNU AGPL v3 LICENSE](LICENSE).
GoToSocial is free software, licensed under the [GNU AGPL v3 LICENSE](LICENSE). We encourage forking and changing the code, hacking around with it, and experimenting.
See [here](https://www.gnu.org/licenses/why-affero-gpl.html) for the differences between AGPL versus GPL licensing, and [here](https://www.gnu.org/licenses/gpl-faq.html) for FAQ's about GPL licenses, including the AGPL.
If you modify the GoToSocial source code, and run that modified code in a way that's accessible over a network, you *must* make your modifications to the source code available following the guidelines of the license:
> \[I\]f you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software.
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.
@ -12,6 +29,8 @@ Spin yourself up a cheap VPS with Linux running on it, or get a homeserver ready
[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
@ -25,7 +44,7 @@ Install [Postgres](https://www.postgresql.org/download/) on your server and run
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
docker run -d --network host --user postgres -e POSTGRES_PASSWORD=some_password postgres
On your local machine (not your server), with Go installed, clone the GoToSocial repository, and build the binary with the provided build script:
```bash
./build.sh
./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:
First cd into the directory you created on your remote machine in step 6:
@ -122,6 +141,6 @@ If you want your user to have admin rights, you can promote them using a similar
Replace `example.org` with your domain and `some_username` with the username of the account you just created.
## 11. Login!
## 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 for this.
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.
tobi
5 years ago
committed by
GitHub