Prepare for staging deployment

.env.sample

@@ -1,3 +1,7 @@
+VERSION=0.1.0
+
+DEVELOPMENT=false
+HOST_NAME=vim.linkedmusic.ca
 
 ## DATABASE ##
 POSTGRES_DB=virtual_instrument_museum

README.md

@@ -8,11 +8,11 @@ ping instrument names and facilitating cross-referencing of instruments across d
 
 ## Installation for Local Development
 
-NOTE: VIM is not yet ready for deployment to a remote server. Use these steps for local testing and development only.
+NOTE: These instructions are for local development only. Refer to the "Installation for Deployment" section for installation on a remote server.
 
 VIM requires Docker Engine with Compose V2. VIM's Docker Compose configuration is written according to the Compose Specification. 
 
-After cloning this repository, set up a local `.env` file. Copy or rename the `.env.sample` file to `.env` and update it to include uncommented environment variables for database credentials `POSTGRES_USER` and `POSTGRES_PASSWORD`. 
+After cloning this repository, set up a local `.env` file. Copy or rename the `.env.sample` file to `.env` and update it to include uncommented environment variables for database credentials `POSTGRES_USER` and `POSTGRES_PASSWORD`. Verify the values of the `DEVELOPMENT` and `HOST_NAME` variables. For local development ONLY, these should be set to "true" and "localhost" respectively.
 
 ```console
 > docker compose build
@@ -21,6 +21,35 @@ After cloning this repository, set up a local `.env` file. Copy or rename the `.
 
 The django development server should now be available at `localhost:8000`.
 
+### Debugging
+
+When installed with `DEVELOPMENT=true` in the `.env` file, some additional modules are included in the application container that provide debugging tools: `django-extensions` and `django-debug-toolbar`. The development installation runs the `runserver_plus` (provided by `django-extensions`) command automatically, which provides an in-browser debug console when errors are raised in the application. `django-extensions` also provides additional tools potentitally useful for development; see the [module documentation](https://django-extensions.readthedocs.io/en/latest/command_extensions.html) for more. The debugging toolbar provided by `django-debug-toolbar` is shown when viewing the development server in the browser.
+
+### Tools for Python Development
+
+VIM uses `poetry` to manage python dependencies and a `poetry.lock` file to ensure reproducible builds in development and production. Dependencies can be found in the `pyproject.toml` file and are divided into three groups: 
+
+1. `main` - the core dependencies required by the application
+2. `debug` - dependencies that provide tools for debugging, and that are installed in the application Docker container only during local development
+3. `dev` - optional dependencies (eg. for code formatting, linting, type checking) that can be useful in the development environment, but are never used in the application container
+
+It is not generally necessary to use `poetry` for development, except when adding additional dependencies. 
+
+## Installation for Deployment
+
+VIM requires Docker Engine with Compose V2. Ensure that the remote server has these installed. 
+
+SSH into the server. After cloning the repository, set up a local `.env` file. Copy or rename the `.env.sample` file to `.env` and update it to include uncommented environment variables for database credentials `POSTGRES_USER` and `POSTGRES_PASSWORD`. Ensure that `POSTGRES_PASSWORD` is secure.
+
+Ensure that the `DEVELOPMENT` variable is set to "false", and that `HOST_NAME` is set to the host name where the VIM instance will be served (for example, "vim.linkedmusic.ca" or "vim.staging.linkedmusic.ca"). 
+
+Then, run
+
+```bash
+> docker compose build
+> docker compose up -d
+```
+
 ## Managing Database Migrations
 
 Django automates changes to the database schema with migrations.

docker-compose.yml

@@ -1,7 +1,11 @@
 # Uses Compose Specification (https://github.com/compose-spec/compose-spec/blob/master/spec.md)
 services:
   app:
-    build: ./web-app
+    build:
+      context: .
+      dockerfile: ./web-app/Dockerfile
+      args:
+        - DEVELOPMENT=$DEVELOPMENT
     container_name: vim-app
     volumes:
       - ./web-app/django:/virtual-instrument-museum/vim-app
@@ -12,8 +16,7 @@ services:
       - POSTGRES_DB=${POSTGRES_DB}
       - POSTGRES_USER=${POSTGRES_USER}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
-    ports:
-      - "8000:8000"
+      - HOST_NAME=${HOST_NAME}
     command: /virtual-instrument-museum/django-startup.sh
 
   postgres:
@@ -33,5 +36,16 @@ services:
       start_period: 30s
     restart: unless-stopped
 
+  nginx:
+    build: ./nginx
+    container_name: vim-nginx
+    restart: unless-stopped
+    environment:
+      - HOST_NAME=${HOST_NAME}
+    ports:
+      - "8000:80"
+    depends_on:
+      - app
+
 networks:
-  vim-net:
+  vim-net:

nginx/Dockerfile

@@ -0,0 +1,3 @@
+FROM nginx:1.25.2
+COPY ./nginx.conf /etc/nginx/nginx.conf
+COPY ./vim.conf.template /etc/nginx/templates/vim.conf.template

nginx/nginx.conf

@@ -0,0 +1,16 @@
+worker_processes 1;
+
+user nginx nginx;
+error_log  /var/log/nginx/error.log warn; # piped to Docker log collector (see nginx Dockerfile)
+pid /var/log/nginx/nginx.pid;
+
+events {
+  accept_mutex off; 
+}
+
+http {
+  include mime.types; # include bundled mime type mapping file
+  access_log /var/log/nginx/access.log combined; # piped to Docker log collector (see nginx Dockerfile)
+
+  include /etc/nginx/conf.d/vim.conf; # include virtual host configurations
+}

nginx/vim.conf.template

@@ -0,0 +1,25 @@
+  upstream vim-app {
+    # define the vim-app upstream server
+    server vim-app:8001 fail_timeout=0;
+  }
+
+  server {
+    # if no host match, close connection
+    listen 80 default_server;
+    return 444;
+  }
+
+
+server {
+  listen 80;
+  client_max_body_size 4G;
+  server_name ${HOST_NAME};
+
+  location / {
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # pass client address to upstream server
+    proxy_set_header X-Forwarded-Proto $scheme; # pass scheme to upstream server
+    proxy_set_header Host $http_host; # pass host to upstream server
+
+    proxy_pass http://vim-app; # proxy request to vim-app upstream server
+  }
+}