Skip to content

Custom Deployments

Jump to bottom
Todd Schiller edited this page Sep 8, 2018 · 39 revisions

Custom Deployments

Running your own instance of the Open Synthesis platform enables you to establish the policies that are best for your community. For example, you might want to run a private instance for your company's team. Alternatively, you might want to try operating a deployment without moderation.

Currently, you can configure the following policies for your deployment:

  • Members-only: a user must be logged-in to view pages
  • Invitation-only: the administrator must invite a user for them to be able to signup
  • Email-optional: a user doesn't need a valid email address to create an account/use the site

In the future, you will also be able to configure moderation requirements/behavior.

Table of Contents

Deploying to Heroku

Heroku is a Platform-as-as-Service (PaaS) provider that provides scalable hosting for Django-powered websites.

Heroku Deploy Button

The Heroku button allows you to create a basic deployment with a single click. The basic deployment is free to run on Heroku because it only makes use of a free dyno and basic addons. NOTE: Heroku's free dynos sleep after 30 minutes of inactivity. For information about upgrading/scaling your application, refer to the Heroku Documentation.

Deploy

Before deploying, Heroku will ask you to configure your deployment. Refer to the Configuration Options section below for information about the available options.

NOTE: the ADMIN_PASSWORD you set will be listed with the other application configuration variables on your application's settings page. After you deploy the application, you should delete the ADMIN_PASSWORD configuration variable.

Heroku CLI

Clone the platform from GitHub:

$ git clone https://github.com/twschiller/open-synthesis.git
$ cd open-synthesis

Create a new Heroku application (requires the Heroku Command Line):

$ heroku create --buildpack heroku/python

Provision the nodejs buildpack for the deployment. The --index 1 option tells Heroku to execute the nodejs buildpack first during deployments.

$ heroku buildpacks:add --index 1 heroku/nodejs

Provision the addons for the application. Note, if you plan on having a significant number of users, you may need to upgrade to paid versions of the addons.

$ heroku addons:create heroku-postgresql
$ heroku addons:create rollbar:free
$ heroku addons:create sendgrid:starter
$ heroku addons:create memcachier:dev
$ heroku addons:create heroku-redis:hobby-dev

Set the application's environment configuration. Refer to the Configuration Options section below for details. Note that DJANGO_SECRET_KEY should be a random string containing least 50 characters (do not use '...').

$ heroku config:set SITE_NAME="Custom Synthesis"
$ heroku config:set SITE_DOMAIN="www.customdomain.com"
$ heroku config:set ADMIN_EMAIL_ADDRESS="[email protected]"
$ heroku config:set DJANGO_SECRET_KEY="..."

Deploy the application:

$ git push heroku master

Perform the initial database setup:

$ heroku run python manage.py migrate
$ heroku run python manage.py loaddata source_tags

Check the application is configured properly:

$ heroku run python manage.py check --deploy

Create a superuser (admin) account:

$ heroku run python manage.py createsuperuser

Ensure that at least one instance of the application is running:

$ heroku ps:scale web=1

NOTE: Heroku's free dynos sleep after 30 minutes of inactivity. For information about upgrading/scaling your application, refer to the Heroku Documentation.

Open the application in your browser:

$ heroku open

Updating Let's Encrypt Certificate

Run certbot's manual verification process:

$ sudo certbot certonly --manual -d www.opensynthesis.org

Set the CERTBOT_PUBLIC_KEY and CERTBOT_SECRET_KEY environment variables to the challenge and the response keys shown by the certbot. The challenge is the key appearing in the challenge URL:

Make sure your web server displays the following content at http://www.opensynthesis.org/.well-known/acme-challenge/[CERTBOT_PUBLIC_KEY] before continuing:

Upload the generated SSL Keys to the Heroku instance:

sudo heroku certs:update /etc/letsencrypt/live/www.opensynthesis.org/fullchain.pem /etc/letsencrypt/live/www.opensynthesis.org/privkey.pem

Administration

Administration is performed via the admin panel available at https://your-deployment.com/admin/.

Sending Invites

To send an invite to a user, click the button "+ Add" to the right of the "Invites" row in the "Invites" section of the admin panel. NOTE: some email clients (e.g., Hotmail), have been flagging invites as spam. You should follow up with the invitee to make sure they've received their invite.

Adding Project News

To add a project news entry, click the button "+ Add" to the right of the "Project Newss" row in the OPENACH section of the admin panel.

Adding/Modifying Source Tags

To modify the set of source tags that analysts can tag evidence sources with. Click the "Evidence source tags" entry in the OPENACH section of the admin panel. Open Syntheses comes with a default set of source tags enabled.

Digest Emails

To set up daily and weekly digests, you can use the Heroku Scheduler add-on. From the command line:

$ heroku addons:create scheduler:standard

Set up the following daily tasks:

python manage.py senddigest daily
python manage.py senddigest weekly

It's OK to run the weekly task on a daily basis. The digest will only send on the day configured by the DIGEST_WEEKLY_DAY environment variable (which defaults to Monday).

Configuration Options

Required Options

Option Description
SITE_NAME The name of your deployment, e.g., "Open Synthesis". If you are planning on running a public instance, please do not use the name "Open Synthesis" because may it cause confusion between your deployment and the official website
SITE_DOMAIN The domain (including subdomain) that the deployment is being hosted at. On Heroku, this is should be set to app-name.herokuapp.com where app-name is the name the Heroku app
ADMIN_EMAIL_ADDRESS Website admin's email address. Used as default email address for sending/receiving email
DJANGO_SECRET_KEY A secret key for verifying the integrity of signed cookies. The key should be a random sequence at least 50 characters long. If you are using the Heroku Deploy Button, a secret key will be generated automatically for you.

Email Options (Optional)

Open Synthesis is configured to use SendGrid. You must either provide a username/password or an API key with the "Send Email" permission. On Heroku, the username/password environment variable are set automatically when you add the SendGrid add-on.

Option Description Default
SENDGRID_API_KEY SendGrid API key for sending digest and invitation emails using the Sendgrid API
SENDGRID_USERNAME SendGrid SMTP username
SENDGRID_PASSWORD SendGrid SMTP password

Account Options (Optional)

Option Description Default
ACCOUNT_REQUIRED Whether a user must have an account to access the site False
ACCOUNT_EMAIL_REQUIRED Whether users must provide a valid email before using the service True
INVITE_REQUIRED Whether a user must receive an invitation to join the site False

Editing Options (Optional)

Option Description Default
EVIDENCE_REQUIRE_SOURCE Whether or not analysts must provide a corroborating source when adding a piece of evidence True
EDIT_REMOVE_ENABLE If enabled, anyone with edit rights for a hypothesis or piece of evidence can remove it True
EDIT_AUTH_ANY If enabled, any authenticated user can modify boards, hypotheses, and pieces of evidence False

Other Options (Optional)

Option Description Default
DEBUG Whether or not the application is running in DEBUG mode. DO NOT ENABLE IN PRODUCTION. False
ENVIRONMENT_NAME An identifier for the application environment, e.g., 'production' or 'development'. Current is only used in the Rollbar setup 'development' if DEBUG, otherwise 'production'
DEFAULT_FROM_EMAIL Default email address for sending emails to users defaults to the value of ADMIN_EMAIL_ADDRESS
DIGEST_WEEKLY_DAY The day of the week (0=Monday, 6=Sunday) to send out weekly digest emails to users. Weekly digests are sent using the sengdigest weekly command Default=0
ROLLBAR_ENABLED Whether or not warnings and errors should be sent to Rollbar for analysis True
PRIVACY_URL URL for your deployment's privacy policy
TWITTER_ACCOUNT The Twitter account associated with the deployment. Used when a page is shared on Twitter.
BANNER_MESSAGE An alert / message to display on each page. URLs will be converted to links

Service Options (Optional)

Option Description Default
CELERY_BROKER_URL The broker, e.g., Redis, RabbitMQ, for Celery to use defaults to the value of REDIS_URL
CELERY_RESULT_BACKEND The backend to use for results from Celery defaults to the value of REDIS_URL
Clone this wiki locally