Skip to content

Latest commit

 

History

History
241 lines (171 loc) · 10.7 KB

README.md

File metadata and controls

241 lines (171 loc) · 10.7 KB

Deployment

  1. Download and extract the latest package.zip from the releases page
  2. Choose a name for your app, we'll refer to this as app-name from now on
  3. [Strongly recommended] Choose an admin email and password to override the defaults ([email protected] and password respectively), we'll refer to these as admin-email and admin-password from now on
  4. [Optional] Configure your deployment:
  5. Follow the instructions to deploy for your platform:
  6. Test your deployment

Configuration

Allowing users to create retros

In order for users to sign-up and create their own retros using the web UI, Postfacto needs Google OAuth setup. For deployments that do not want to setup Google OAuth, you will need to create your retros through the admin console of your server via <app-name>.<cf-url>/admin

  1. Go to Google Cloud Console and create a new project
  2. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID > Web application
  3. Choose a name for your app
  4. In Authorized JavaScript Origins, set it to the public URL of your app-name. For example: if deploying to Heroku, your public URL will be https://<app-name>.herokuapp.com
  5. You can leave redirect blank
  6. Take note of your client-id that is generated
  7. Add "google_oauth_client_id": {{client-id}} to the config.js for your installation

Enabling analytics

If you'd like to have your instance send analytics data to the Postfacto team so they can learn about how you're using it and continue to improve it you can! To switch this on add "enable_analytics": true to the config.js object for your installation. Please note that we do not record any personal data (such as emails or retro data). As we are recording events from you we will however see the URL of the web client for your instance. If you're not comfortable with this don't worry, this feature is disabled by default.

Changing session timeout

You can customise this window with the SESSION_TIME env variable to the env on deploy. To set a session time of 1 hour for example:

SESSION_TIME=60 ./deploy.sh <app-name>

Using TLS for database connections

If your database only accepts incoming TLS encrypted connections, you will need to modify the application settings to include the appropriate SSL parameters. Please add the below configuration snippet to package/assets/config/database.yml prior to executing deploy.sh.

For MySQL

production:
  sslmode: preferred # or verify_identiy, verify_ca
  sslca: /etc/ssl/certs/ca-certificates.crt # or alternate location where your ca file is located

When this is not set, you will receive this error:

Connections using insecure transport are prohibited while --require_secure_transport=ON.

More information about MySQL SSL modes can be found here.

For PostgreSQL

production:
  sslmode: prefer # or verify-full, verify-ca, require
  sslca: /etc/ssl/certs/ca-certificates.crt # or alternate location where your ca file is located

More information about SSL modes can be found here.

Removing Redis dependency

If you are on a later version than 4.3.0 and using Postgres, Redis is no longer required. Instead set the environment variable USE_POSTGRES_FOR_ACTION_CABLE=true on deploy.

However, note that for larger retros the live websocket updates may stop working (see #346) as the Postgres adapter has an 8kB payload limit.

Tanzu Application Service

Initial deployment

  1. Set yourself up with an organization and space in your TAS account to deploy Postfacto to

  2. Add a database (Postgres or MySQL) and a Redis service instance to your space from the Marketplace. Name these services postfacto-db and postfacto-redis

  3. Run the TAS deployment script from the tas directory, either:

    ADMIN_EMAIL=<admin-email> ADMIN_PASSWORD=<admin-password> ./deploy.sh <app-name>

    or, to use the default admin credentials ([email protected] and password):

    ./deploy.sh <app-name>

    Take note of the URL that has shown up in the routes: section of the script output, going forward referred to as <app-url>

  4. Log in to the Postfacto admin dashboard (email: [email protected] and password: password) to check everything has worked at <app-url>/admin

  5. Create a retro for yourself by clicking on 'Retros' and the 'New Retro'

  6. Log in to your retro at <app-url>/retros/your-retro-slug

  7. Share the URL and password with your team and then run a retro!

Upgrading a deployment

  1. Presuming the steps in the Initial deployment section have been completed, run the upgrade script from the tas directory: 
    ./upgrade.sh <app-name>

Tanzu Kubernetes Grid (vSphere)

Prerequisites

  1. A vSphere instance version 6.7u3 or higher, with Tanzu Kubernetes Grid (TKG) provisioned

  2. A network load balancer installed and configured on your TKG cluster (e.g. MetalLB)

  3. A default storage class available in your TKG cluster (e.g. vSphereStorageClass)

Initial deployment

  1. Install kubectl to your local machine

  2. Install helm to your local machine

  3. Make sure kubectl is configured to connect to the TKG cluster (ask your administrator for the configuration)

  4. Run the deployment script from the tkg directory, either:

    ADMIN_EMAIL=<admin-email> ADMIN_PASSWORD=<admin-password> ./deploy.sh <app-name>

    or, to use the default admin credentials ([email protected] and password):

    ./deploy.sh <app-name>

  5. Keep note of the application url output by the deployment script, going forward referred to as tkg-url

  6. Log in to the admin dashboard at <tkg-url>/admin (email: [email protected] and password: password)

  7. Create a retro for yourself by clicking on 'Retros' and then 'New Retro'

  8. Log in to your retro at <tkg-url>/retros/your-retro-slug

  9. Share the URL and password with your team and then run a retro!

Upgrading a deployment

  1. Presuming the steps in the Initial deployment section have been completed, run the upgrade script from the tkg directory: 
    ./upgrade.sh <app-name>

Cloud Foundry

Initial deployment

  1. Set yourself up with an organization and space in your CF to deploy your Postfacto to

  2. Take note of your CF url, going forward referred to as cf-url

  3. Add a database (Postgres or Mysql) and a Redis service instance to your space from the Marketplace; name these services postfacto-db and postfacto-redis

  4. Run the CF deployment script from the cf directory, either:

    ADMIN_EMAIL=<admin-email> ADMIN_PASSWORD=<admin-password> ./deploy.sh <app-name>

    or, to use the default admin credentials ([email protected] and password):

    ./deploy.sh <app-name>

  5. Log in to the Postfacto admin dashboard to check everything has worked at <app-name>.<cf-url>/admin

  6. Create a retro for yourself by clicking on 'Retros' and then 'New Retro'

  7. Log in to your retro at <app-name>.<cf-url>/retros/your-retro-slug

  8. Share the URL and password with your team and then run a retro!

Upgrading a deployment

  1. Presuming the steps in the Initial deployment section have been completed, run the upgrade script from the cf directory: 
    ./upgrade.sh <app-name>

Migrating a deployment

  1. If you'd previously deployed a version of Postfacto prior to 4.0, run the migration script from the cf directory: 
    ./migrate.sh <web-app-name> <api-app-name>
    Note that the admin panel will move from <api-app-name>.<cf-url>/admin to <web-app-name>.<cf-url>/admin and the API app will be deleted

Heroku

Initial deployment

  1. Install the Heroku CLI

  2. Run the Heroku deployment script from the heroku directory, either:

    ADMIN_EMAIL=<admin-email> ADMIN_PASSWORD=<admin-password> ./deploy.sh <app-name>

    or, to use the default admin credentials ([email protected] and password):

    ./deploy.sh <app-name>

    If you want to deploy to the EU region, rather than the default US region, prefix the deploy command with HEROKU_REGION=eu

  3. Log in to the Postfacto admin dashboard to check everything has worked at <app-name>.herokuapp.com/admin

  4. Create a retro for yourself by clicking on 'Retros' and then 'New Retro'

  5. Log in to your retro at <app-name>.herokuapp.com/retros/your-retro-slug

  6. Share the URL and password with your team and then run a retro!

Upgrading a deployment

  1. Presuming the steps in the Initial deployment section have been completed, run the upgrade script from the heroku directory: 
    ./upgrade.sh <app-name>

Migrating a deployment

⚠️ Warning: the Heroku migration will attempt to migrate your data to a new database instance and delete the old one. Take a look at what the script is doing and make sure you understand the implications before running it.

  1. If you'd previously deployed a version of Postfacto prior to 4.0, run the migration script from the heroku directory: 
    ./migrate.sh <web-app-name> <api-app-name>
    Note that the admin panel will move from <api-app-name>.herokuapp.com/admin to <web-app-name>.herokuapp.com/admin and the API app will be deleted

Testing your deployment

  1. Log in to the Postfacto admin dashboard
  2. Create a new admin user for the test to use by clicking on 'Admin Users' and then 'New Admin User'. Take note of the email and password you use, as these will be used in the next step
  3. Run the smoke test script from the root of the package directory: 
    ./smoke-test.sh <app-url> <app-admin-url> <test-admin-email> <test-admin-password>