DEPLOYMENT.md.tt

# How to deploy <%= app_name %>

This document covers the steps need to deploy the application to an existing environment. To create a new environment, refer to `PROVISIONING.md`.

* **Developers:** this project is built and deployed using Capistrano, which is the `cap` command. Refer to the *Capistrano* section.
* **System administrators:** once deployed, the various processes and configuration can be maintained with familiar Linux commands. Refer to the *Server maintenance* section.


## Capistrano

### Environments

* **staging** is deployed from the `development` branch.
* **production** is deployed from the `master` branch.

### Prerequisites

Capistrano runs on your local machine and uses SSH to perform the deployment on the remote server. Therefore:

* The Capistrano gem must be installed (see `README.md` for project setup instructions).
* You must have SSH access to the production/staging server.
* Your SSH key must be installed on the server in `~deployer/.ssh/authorized_keys`.
* You must have SSH access to Git repository (using your SSH key).

### Performing a graceful deployment (no migrations)

This will deploy the latest code from `master`. Make sure to `git push` your changes first, or they will not apply.

```
bundle exec cap production deploy
```

### Performing a full deployment

If there are data migrations or other changes that require downtime, perform the deployment using the following task:

```
bundle exec cap production deploy:migrate_and_restart
```

This will stop the app and display a maintenance page during the deployment.


## Server maintenance

This application consists of two executables that run as the `deployer` user:

* Puma is the application server that services Rails HTTP requests
* Sidekiq is the background worker that services the job queue stored in Redis

These in turn rely on the following services:

* PostgreSQL
* Redis
* Nginx

### Controlling processes

All processes are set up to start automatically when the server boots, and can be controlled using the standard Ubuntu `systemctl` command:

```
sudo systemctl <start|stop|restart|status> postgresql
sudo systemctl <start|stop|restart|status> nginx
sudo systemctl <start|stop|restart|status> <%= capistrano_app_name %>-puma.service
sudo systemctl <start|stop|restart|status> <%= capistrano_app_name %>-sidekiq.service
```

Note that the `deployer` user has permission to restart `<%= capistrano_app_name %>-puma.service` and `<%= capistrano_app_name %>-sidekiq.service`, but nothing else. All other `systemctl` commands require `root`.

### Configuration

All configuration values required by the application can be changed here:

```
/home/deployer/apps/<%= capistrano_app_name %>/shared/.env.production
```

After making changes to this file, be sure to restart the application:

```
sudo systemctl restart <%= capistrano_app_name %>-puma.service
sudo systemctl restart <%= capistrano_app_name %>-sidekiq.service
```