soapbox

Soapbox -- the web application hosting platform

Soapbox provides managed web application hosting services, encapsulating best-practices for deployment and operations. Soapbox is a platform on top of cloud services that allows teams to focus on development and provides scaling and monitoring without custom configuration.

Getting started

Quick and dirty using docker-compose

• Install Go 1.8 or greater - see directions here.
• Install Docker and Compose. (Note that Mac and Windows users already have Compose if they install Docker.)
• Install modd using go get github.com/cortesi/modd/cmd/modd.
• Run docker-compose up to build, create and start the containers with streaming logs.
• Run modd in another terminal to start the file-watcher. Any changes to local files will rebuild binaries and restart services as needed.
• Visit http://localhost:3000/ and go!
  • Note that you'll have to set up Github OAuth (instructions below) in order to create and manage applications.
• When done, CTRL-C to stop the containers. Don't use docker-compose down, as that will remove your containers and erase the DB.
• To start back up again, use docker-compose up --no-recreate.

Useful docker-compose commands

• Connect to the soapboxd container:

$ docker-compose run soapboxd sh

• Connect to the database console:

$ docker-compose run postgres psql -h postgres -U soapbox -d soapbox_dev

• Connect to the rails console:

$ docker-compose run rails rails c

Possible issues when working w/ docker-compose

• If Rails did not gracefully shutdown, you may see an error when running docker-compose that says, "A server is already running." More than likely, a server is not running; docker only thinks one is. Deleting the file web/tmp/pids/server.pid from the soapbox project root should solve this issue.
• Getting Rails errors on the landing page? This is usually a product of having no users available in the database, so navigating to /user/new and creating a user should fix the problem. If not, try clearing the _web_session cookie from the page.

Local requirements without docker-compose

• Go 1.8 or greater - see directions here
• Ruby 2.2 or greater - see directions here
• PostgreSQL 9.5 or greater - Ubuntu | Mac
• Terraform 0.9.11 or greater - Download and install Terraform from here.

Running the server and client locally

1. Create a PostgreSQL db and its initial schema:

$ createdb soapbox_dev
$ psql -f db/schema.sql -d soapbox_dev

1. Build and install the Soapbox API server (soapboxd) and CLI client (soapboxcli):

$ mkdir -p $(go env GOPATH)/src/github.com/adhocteam
$ go get github.com/adhocteam/soapbox/...

You may need to add the bin directory under $GOPATH (the go tool uses $HOME/go for GOPATH if you don't set it explicitly in your environment), if you didn't do that when you installed Go initially.

$ export PATH=$PATH:$(go env GOPATH)/bin

1. Run the API server:

$ PGDATABASE=soapbox_dev PGSSLMODE=disable AWS_REGION=us-east-1 soapboxd &

• If your database user is password protected, you may need to pass PGPASSWORD=yourpgpass to the command above as well.

1. Try out the CLI client:

$ soapboxcli list-applications

1. Install the web client:

$ cd web
$ gem install bundler
$ bundle install

1. Run the web client and try it out:

$ bin/rails server &
$ open http://localhost:3000/

GitHub OAuth

In order to use Soapbox with private repositories, you must grant the application access through OAuth.

1. Go to the OAuth applications page and click on Register a new application.
2. Give your application a name and a homepage URL (this could be localhost:3000 or a registered domain).
3. For Authorization callback URL, enter your homepage URL followed by /auth/github/callback.
4. When you submit, you will see a Client ID and a Client Secret. Set these as the environment variables GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET (be sure to restart your Rails server after these are set). If you are using docker-compose to build and run soapbox, add these to your .env file.
5. Create a user in the Soapbox web UI, click Link to GitHub on your profile page, and grant the requested permissions.

Developing Soapbox

Installing protoc

protoc is the program that compiles protobuf files into language-specific generated code.

Homebrew on macOS

$ brew install protobuf

Any platform

1. Download the latest protoc for your platform here
2. Unzip the file
3. Copy the bin/ folder to /usr/local/bin
4. Copy the include/ folder to /usr/local/include

Making changes to protobufs

Soapbox uses Protocol Buffers via gRPC for clients and servers to exchange messages and call API methods. These definitions are stored in the soapboxpb directory in .proto files. If you change these files, you must re-generate the Go and Ruby code that the API server and the Rails app rely on, respectively. Additionally, if you make a change to the database, you must update schema.sql.

$ make protobufs
$ make models
$ make all

Making changes to the database schema

Soapbox uses xo to generate database models.

To install, run the command:

$ go get -u github.com/knq/xo

Then, after you modify db/schema.sql, run make schema to generate the database models.

(Go 1.8.0 has a known bug which prevents xo from running, upgrade to 1.8.1 or higher)

Go dependencies

Soapbox uses dep for dependency management. Follow the below flow to add imports:

• Add the import to the code
• Run dep ensure to make sure that the manifest, lock file, and vendor folder are updated

Running these steps will clone the repo under the vendor directory, and remembers the revision used so that everyone who works on the project is guaranteed to be using the same version of dependencies.

Design documentation

• Architecture document
• Product announcement