Production Installation

Server

System Requirements

Provision a server with at least:

• 2 CPU
• 1 GB Memory
• 50 GB Disk
• Ubuntu 22.04 LTS (x64)

Network

You will need access on:

• Port 8000: Optional TEMPORARY port for testing your installation
• Port 80: for HTTP
• Port 443: for HTTPS
• Port ???: for SSH (choose your own adventure!)

Installation

Initial Setup [Stack]

1. SSH into your server
2. Bring it up-to-date with:

   sudo apt update
   supo apt upgrade -y
   sudo apt install git -y
   

3. Set up your installation directory [ Replace {USERNAME} with your sudo user's name]:

   sudo mkdir /usr/local/apps
   cd /usr/local/apps
   sudo chown {USERNAME} ./
   git clone https://github.com/Ecotrust/wcbluepages.git
   cd ./wcbluepages
   

4. Install depencencies* and set up your virtual python environment:

   cd /usr/local/apps/wcbluepages/deploy/
   sudo ./production_linux_deps.sh
   ./linux_pyenv.sh
   source /usr/local/apps/env/bin/activate
   

   *Note: If NOT using Ubuntu 22.04 Jammy LTS, you will need to install each of the dependencies in deploy/production_linux_deps.sh by hand (unless you are running 20.04 Focal LTS, in which case you can run deploy/linux_deps.sh which was intended for development installation which is currently bound to Focal).
5. Configure special file permissions:

   sudo groupadd mediausers
   sudo adduser www-data mediausers
   sudo chgrp -R mediausers /usr/local/apps/wcbluepages/bluepages/media_root
   sudo chmod -R 770 /usr/local/apps/wcbluepages/bluepages/media_root
   

DJ Alias:

The following steps create the shortcut dj to replace needing to write /usr/local/apps/env/bin/python /usr/local/apps/wcbluepages/bluepages/manage.py everytime you need to run a common Django command.

sudo vim /etc/bash.bashrc

Add the following lines to the bottom:

alias dj="/usr/local/apps/env/bin/python /usr/local/apps/wcbluepages/bluepages/manage.py"
alias djrun="dj runserver 0.0.0.0:8000"

To use your new alias either log out and back in again, or run:

source /etc/bash.bashrc

From now on, every time you connect to the server you will have access to these shortcuts.

Once dj is working, test it out by organizing your static media where your server can find it later:

dj collectstatic

Database:

1. Create Your Database User : Replace {USERNAME} with an appropriate username for your database user below. You will be prompted to provide a new {PASSWORD} as well.

   sudo -u postgres createuser -s -P {USERNAME}
   sudo -u postgres createdb -O {USERNAME} bluepages
   

2. Override default settings with your database user config:

   cp /usr/local/apps/wcbluepages/bluepages/bluepages/local_settings.py.template /usr/local/apps/wcbluepages/bluepages/bluepages/local_settings.py
   vim /usr/local/apps/wcbluepages/bluepages/bluepages/local_settings.py
   

   Replace the content in curly braces below with your {USERNAME} and {PASSWORD} values you created earlier in this step:

   DATABASES = {
       'default': {
           'ENGINE': 'django.contrib.gis.db.backends.postgis',
           'NAME': 'bluepages',
           'USER': '{USERNAME}',
           'PASSWORD': '{PASSWORD}',
           'HOST': 'localhost',
           'PORT': 5432,
       }
   }
   

3. Restart Postgres, then apply the database migrations

   sudo service postgresql restart
   dj migrate
   dj createsuperuser
   dj loaddata /usr/local/apps/wcbluepages/bluepages/address/fixtures/initial.json
   dj loaddata /usr/local/apps/wcbluepages/bluepages/app/fixtures/initial.json
   

App Server Initialization and Configuration

1. More Local Settings updates:

   vim /usr/local/apps/wcbluepages/bluepages/bluepages/local_settings.py
   

   Update ALLOWED_HOSTS and SECRET_KEY:

   • ALLOWED_HOSTS
     • This is a list of strings of the URLs you wish to allow your site to be accessed at. If your website is 'foo.com', then your value may look something like this:
       • [ 'foo.com', 'www.foo.com' ]
     • If you're not too concerned about security, accept any connection with [ '*' ]
   • SECRET_KEY:
     • This is just a random string that the server uses to verify that it's talking to itself or another approved server. You should never need to remember this or type it in, so button mash and make it complex and log.

2. Install and initialize NGINX and uWSGI:

   sudo /usr/local/apps/wcbluepages/deploy/init_servers.sh
   

3. Configure NGINX Edit the nginx configuration:

   sudo vim /etc/nginx/sites-available/bluepages
   

   Update the following:

   • server_name: replace _ with the url(s) and/or IP address(es) you intend to access the site with

4. Test and restart NGINX Test NGINX with the following command:

   sudo nginx -t
   

   You should see a message confirming that the configuration file is good. If not, review your changes.

   If the configuration file checks out, restart nginx:

   sudo service nginx restart
   

Certbot (HTTPS/SSL)

1. Ensure you have the latest Snap packages, and replace any prior Certbot installations:

   sudo snap install core
   sudo snap refresh core
   sudo apt-get remove certbot
   sudo snap install --classic certbot
   sudo ln -s /snap/bin/certbot /usr/bin/certbot
   sudo certbot --nginx
   

2. Answer the prompts from Certbot:
   • Email address for renewal notifications (your address or that of your team)
   • Read the terms and accept with Y
   • Share your email address with EFF? (Y/N)
   • If you entered multiple names for 'server_name' in your bluepages.conf file, specify which ones you wish to get certificates for (or just hit enter to accept all).

TODO:

• Uptime monitoring
• Hardware monitoring
• Automatic updates