Developers wanting to work on [Gab Social](https://code.gab.com/gab/social/gab-social) source code and make changes to the system must configure a host for use with Gab Social's development environment.
The instructions in this file do not create a production-grade host that is secure and can scale. Instead, these instructions deliver a working environment tuned for making changes to Gab Social and for quickly iterating on those changes to get stuff done.
[Gab Social](https://code.gab.com/gab/social/gab-social) development has been tested on [Ubuntu 18.04LTS](https://www.ubuntu.com/download/desktop). As we continue to migrate further away from Gab Social's code, at least MacOS will be supported as a choice.
We are unlikely to support Windows as a host OS because no part of our software development infrastructure is based on Windows. We will, however, be happy to review and accept your pull requests adding Windows support for development and even production hosting if you think that's not too nutty.
## Superuser Host Access Rights Required
This document describes commands intended to be run in a terminal. It also describes changes needed in some components' configuration files. Some of these actions must be performed with the user account you will use for day-to-day development. And, some of the commands need to be performed as the superuser (root) or a user with equivalent administrative privileges.
When superuser permissions are required,
## Extend Ubuntu repositories when using Ubuntu 18.04.1LTS or later
Starting with Ubuntu 18.04.1 LTS, Canonical removed the multiverse and restricted repositories from the sources.list in `/etc/apt/`. It is now necessary to add those repositories manually , otherwise the installation of the following dependencies will fail.
- *ImageMagick* - Gab Social uses imagemagick for image related operations
- *FFMPEG* - Gab Social uses ffmpeg for conversion of GIFs to MP4s
- *libprotobuf-dev* and *protobuf-compiler* - Gab Social uses these for language detection
- *nginx* - nginx is our frontend web server
- *Redis* - Gab Social uses redis for its in-memory data structure store
- *postgresql* - Gab Social uses PostgreSQL as its SQL database
- *Node.js* - Node is used for Gab Social's streaming API and other platform services
- *Yarn* - Yarn is a Node.js package manager
- *gcc, g++, etc.* - these are needed for the compilation of Ruby using ruby-build and to build Node.js extensions
## Dependency Installation
All dependencies should be installed as the system superuser (root). Either use the `sudo` command as required, or by first switching to the superuser using the following command:
```sh
sudo -i
```
If you become root, please be sure to switch back to your regular user account when instructed to do so later.
Node.js is required for running the [Gab Social](https://code.gab.com/gab/social/gab-social) Streaming API server and for other system management tasks related to the Gab Platform.
Gab Social requires a standard non-root user account for day-to-day operations and work. This can be your own account or (if following this document for the first time) the `gabsocial` user.
Creating a `gabsocial` user is simple and can make following the rest of this guide very simple.
Create a user for a [PostgreSQL](https://www.postgresql.org) instance:
```
# Launch psql as the postgres user
sudo -u postgres psql
# In the following prompt
CREATE USER gabsocial CREATEDB;
\q
```
**Note** that we do not set up a password of any kind, this is because we will be using ident authentication. This allows local users to access the database without a password.
### Switch back to your account
If you became the root user to install system dependencies, please relinquish superuser privileges and return to your user account.
```sh
exit
```
### Configure your working environment
The public-facing Web service `gabsocial-web` is currently built using Ruby On Rails. A developer workstation user account, therefore, must configure [`rbenv`](https://github.com/rbenv/rbenv) and [`ruby-build`](https://github.com/rbenv/ruby-build) as follows:
[Ruby](https://www.ruby-lang.org/en/) version which [Gab Social](https://code.gab.com/gab/social/gab-social) uses. That version will also need to be enabled.
Now that [Ruby](https://www.ruby-lang.org/en/) is enabled, we will clone the [Git Social git repository](https://code.gab.com/gab/social/gab-social) and install the [Ruby](https://www.ruby-lang.org/en/) and [node.js](https://nodejs.org/en/) dependancies.
# Hop into the project directory (all are welcome!)
cd ~/projects/gab-social
# Install bundler
gem install bundler
# Use bundler to install the rest of the Ruby dependencies
bundle install
# Use yarn to install node.js dependencies
yarn install --pure-lockfile
# To setup the `gabsocial_development` database, run:
bundle exec rails db:setup
# Use foreman to start things up
gem install foreman
foreman start
```
At this point, you should be able to open `http://localhost:3000` in your browser and log in using the default credentials `admin@localhost:3000` and password `administrator`.
Some additional useful commands:
```sh
# pre-compile the front-end assets and fun stuff
bin/rails assets:precompile
# manually start the webpack dev server
./bin/webpack-dev-server
# You can then run Gab Social with:
bundle exec rails server
```
## Managing your development environment
It is assumed that development hosts are not publicly accessible. For best security, there should be no route from a public network to your Gab Social development workstation.
By default, your development environment will have an admin account created for you to use - the email address will be `admin@YOURDOMAIN` (e.g. admin@localhost:3000) and the password will be `administrator`.
You can run tests with:
rspec
You can check localization status with:
i18n-tasks health
And update localization files after adding new strings with:
Federation absolutely requires your Gab Social instance to have a domain name. If you want to operate a permanently-federated development server (Gab does), set up a [Gab Social](https://code.gab.com/gab/social/gab-social) instance with a domain, and update it against your development fork/branch while doing that development on your local workstation or as a team.
To test federation on a *local* developer workstation, localhost => world tunneling can be made possible yourself on a domain you manage or by using services like [ngrok](https://ngrok.com).
Ngrok and similar services give you a random domain on each start up and iteration of your development build. This is good enough to test how the code you're working on handles real-world situations. But, your instance domain name is unique every time you run it.
For managing a production server, a service like Ngrok is the definition of Doing It Wrong™.
### Federation tips
Generally, federation is tricky to work on because it's hard to test. When you are testing with a disposable instance, you are polluting the database of the real server(s) you are testing against.
It is possible to use Ngrok for one session, record the exchanges from its web interface, and use that data to create fixtures and build test suites. From then on, the developer can continue working against the tests instead of live servers.
Study the code and RFCs before implementing federation features or changes.
### Remote Development
If the development environment is running remotely, setting the `REMOTE_DEV` environment variable will instruct your instance to use "letter opener web"
Letter Opener launches a local browser. Letter Opener Web collects emails and displays them at /letter_opener.
