Post deployment

The content of this article applies to the open source version of Osso and is not relevant to our paid plans. If you're already an Osso customer, skip ahead to Configuration.

Once you successfully deploy Osso, visit the index path - if you see the Osso login screen, then you're ready to start setting up your instance.

Setup script#

Osso provides a setup script to bootstrap your instance with a first user and default OAuth Clients. Separately Osso also provides a seed script that's more useful for local development and CI testing - we use it in our Cypress tests.

If you use the Deploy to Heroku button Osso will run this script for you. Otherwise run

bundle exec rake osso:bootstrap

This task depends on having the ENV variable ADMIN_EMAIL set - see our Environment Variables guide. You can set this when running this script like so: bundle exec rake osso:bootstrap

The script will create the first user for that email, and send an email invitation to confirm the account and choose a password. You'll be able to invite subsequent users via email through Osso's admin UI.


We recommend maintaining a GitHub repository for your Osso instance. This will let you implement GitHub based deploys on Heroku, utilize Dependabot for package updates, and manage any updates made to the main Osso project using Git.

You can also treat the main Osso repository as an upstream remote. Note that Osso uses main as the default branch.

The simplest approach is to first Fork the main Osso repository to your own account.

Then, from the command line, clone your fork and add the upstream remote:

git clone[your-username]/osso.git
cd osso
git remote add upstream git://

You can then merge upstream changes to your local clone, and push to your GitHub repo:

git fetch upstream
git merge upstream/main main
git push origin/main

You can use GitHub actions, Buildkite, or any CI tool to run Osso's tests as part of your deployment process.