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.
- 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 usedocker-compose down
, as that will remove your containers and erase the DB. - To start back up again, use
docker-compose up --no-recreate
.
- 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
- 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 fileweb/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.
- 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.
- Create a PostgreSQL db and its initial schema:
$ createdb soapbox_dev
$ psql -f db/schema.sql -d soapbox_dev
- 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
- 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.
- Try out the CLI client:
$ soapboxcli list-applications
- Install the web client:
$ cd web
$ gem install bundler
$ bundle install
- Run the web client and try it out:
$ bin/rails server &
$ open http://localhost:3000/
In order to use Soapbox with private repositories, you must grant the application access through OAuth.
- Go to the OAuth applications
page and click on
Register a new application
. - Give your application a name and a homepage URL (this could be
localhost:3000
or a registered domain). - For
Authorization callback URL
, enter your homepage URL followed by/auth/github/callback
. - When you submit, you will see a
Client ID
and aClient Secret
. Set these as the environment variablesGITHUB_OAUTH_CLIENT_ID
andGITHUB_OAUTH_CLIENT_SECRET
(be sure to restart your Rails server after these are set). If you are usingdocker-compose
to build and run soapbox, add these to your.env
file. - Create a user in the Soapbox web UI, click
Link to GitHub
on your profile page, and grant the requested permissions.
protoc
is the program that compiles protobuf files into language-specific generated code.
$ brew install protobuf
- Download the latest
protoc
for your platform here - Unzip the file
- Copy the
bin/
folder to/usr/local/bin
- Copy the
include/
folder to/usr/local/include
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
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)
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.