How can I quickly set up Primero

Here is a quick overview of the steps required to set up Primero on a linode server using Chef. It is structured into tasks to be completed on the Linode virtiual machine and then tasks to be completed on a local machine (like a laptop)

Each section will be explained in detail.

Overview of Linode Tasks (from now on this will be referred to as the target machine)

  • Log in to Linode and set up a small virtual machine (recommended is a 4GB instance) running Ubuntu 16.04 LTS.
  • Create a user on the target machine with passwordless sudo access
  • Set up DNS so that a domain name resolves to the target machine
  • Install a digital certificate based on the domain name using the certbot application created by Lets Encrypt. If you use the "recipe[primero::letsencrypt]", in your json configuration (explained later) then chef will do this for you

Overview of Local Tasks (from now on this will be referred to as the deployment machine)

  • Install Chef and Knife
  • Clone the Primero repository and make sure your public SSH key has been added to the github repository
  • Create a configuration file for Chef and run the config file using chef

Tasks on the target machine

Log in to Linode and set up a linode running Ubuntu 16.04 LTS.

  • Create a linode using the web interface
    _ Note that the version of Ubuntu is important_

After that completes note the SSH access details (like ssh root@xxx.xxx.xxx.xxx ) on the Linodes tab in the Linode interface.

Create a user on the target machine with passwordless sudo access

  • Using a Terminal log in using the SSH details noted above. Create a new user
root@machine:~# adduser <user>

Give this new user access to sudo

root@machine:~# adduser <user> sudo

Set up DNS so that a domain name resolves to the target machine

  • Add a Domain Zone on Linode.

The IP address if the machine you just set up must point tot the domain and the nameservers also need to resolve

Tasks on the deployment machine

Copy your ssh ID to the target machine

ssh-copy-id @xxx.xxx.xx.xxx

Install Chef and Knife

Open a terminal and do

$ wget https://packages.chef.io/stable/debian/6/chefdk_0.9.0-1_amd64.deb
$ sudo dpkg -i chefdk_0.9.0-1_amd64.deb
$ chef verify
$ chef gem install knife-solo --version 0.4.3

Note that the version number of chef is important

Clone the Primero repository and make sure your public SSH key has been added to the repository

Copy your public ssh key using

$ pbcopy < ~/.ssh/id_rsa.pub

and paste it into the ssh keys on github. Then clone the repository using

$ git clone https://github.com/primeroIMS/primero.git

Create a configuration file for Chef and run the config file using chef

In the cookbook folder of the checkout there is a file called dev_node.json which is an example configuration file for chef. Paste appropriate certificates and keys for couchdb and the deploy key
Here we are deploying the maint_1.6 branch with unattended upgrades and a lets encrypt certificate. These are called recipies (there are others available)

{
  "couch_db": {
    "config": {
      "httpd": {
        "bind_address": "0.0.0.0"
      }
    }
  },
  "primero": {
    "environment": "dev",
    "rails_env": "production",
    "server_hostname": "somehost.com",
    "no_reseed": false,
    "git": {
      "repo": "<your git repo>",
      "revision": "maint_1.6"
    },
    "letsencrypt": {
      "email": "your@email.com",
      "couchdb": true
    },
    "couchdb": {
      "password": "",
      "ssl": {
        "cert": "",
      "key": ""
      }
    },
    "deploy_key": "",
    "ssl": {
      "crt": "",
      "key": ""
    }
  },
  "unattended-upgrades": {
    "send_email": true,
    "email_address": "primero_support@your.org",
    "auto_reboot": true
  },
  "run_list": [ 
    "recipe[primero::default]",
    "recipe[primero::letsencrypt]", 
    "recipe[chef-unattended-upgrades::default]" 
  ]
}

Make sure you copy the certificates exactly (without spaces for example). A useful command is this for example

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' couch_ca.cert

After this is done run the deployment command (from the cookbook folder)

ssh user@xx.xx.xx.x 'which chef-solo' || knife solo prepare --bootstrap-version=11.10.4 user@xx.xx.xx.xx

knife solo cook user@xx.xx.xx.xx dev-node.json

Note that if you want to deploy a branch which is not the latest this is (maint_1.6 at the time of writing) then you need to run chef from the branch you want to deploy. For example this is for the 1.5 release

git checkout --track maint_1.5/maint_1.5

and then

knife solo cook user@xx.xx.xx.xx dev-node.json

Hey @irlawrence …this post helped me a lot to deploy my production setup for primero. Thank you soo much for covering such small details.
If possible could you please tell me what I could do to change logo of primero etc after deploying the production setup on the server.
Thanks in advance. Any kind of help is appreciated.

The best way to add a logo is to log in as a super user and then edit the agency screen in settings


If you wish to change the main primero logo then you need to create (or use an existing) rake task for that and also recompile the assets. See here for the details