Update deployment configurations and ports

.env.sample

@@ -1,9 +1,9 @@
 APP_VERSION=3.2-0.11.4
 COMPOSE_PROJECT_NAME=cantus
 
-#Sets the DEBUG Django setting
-#PORT = 8000 for development, PORT = 80 for production
-PORT=8000
+#When DEVELOPMENT is False, Django's DEBUG setting
+#is False and app is served by gunicorn
+DEVELOPMENT=False
 
 #Postgres authentication variables
 POSTGRES_DB=cantus_db

README.md

@@ -28,9 +28,11 @@ The build process relies on environment variables specified in an `.env` file lo
 
 Make a copy of `.env.sample` and name it `.env`. You must make two modifications to this file before the docker containers will build.  Both `POSTGRES_PASSWORD` and `RABBIT_PASSWORD` should be uncommented and set with secure passwords.
 
+Before launching the site, ensure that the `DEVELOPMENT` variable is set correctly. For development, it should be set to `True`; for deployment, it should be `False`. This variable configures the application's debug settings. Deploying the website with `DEVELOPMENT=True` would leak debugging information on a live server and use Django's development server rather than gunicorn and must be avoided.
+
 #### Handling `postgres` authentication issues
 
-When the containers are launched, a volume, `data/postgres`, will be created. When the `POSTGRES_PASSWORD` is changed between builds of the docker containers, the `postgres` container might run into an authentication problem because of the existing volume. If you run into that problem, make sure to remove the volume and re-launch the containers
+When the containers are launched, a directory at `./data/postgres`, will be created and mounted to the `postgres` container. When the `POSTGRES_PASSWORD` is changed between builds of the docker containers, the `postgres` container might run into an authentication problem because of the existing volume. If you run into that problem, make sure to remove the volume and re-launch the containers
 
 ```
 docker rm -v <container-id>
@@ -39,49 +41,72 @@ rm -r data
 
 ### Launch in development
 
-In the `.env` file, the `PORT` variable is set to `8000` (development) by default. This will turn on Django's debug mode, showing detailed traces when Django encounters errors, as well as turn off security settings that might stop you from accessing the site locally. In production, this should be set to `80`.
+In the `.env.sample` file, the `DEVELOPMENT` variable is set to `False` by default. For local development, set this to `True` to turn on Django's debug mode, which allows you to access detailed traces when Django encounters errors. For deployment on a server, this should remain set to `False`.
 
 > **Windows Users:** Make sure `/app/django-config.sh` has `LF` line endings before launching. This file gets copied over into an Ubuntu container and will break the process if git automatically checked out the file using Windows (`CRLF`) line endings.
 
 Execute the following commands from the root directory of the repo:
 
 ```sh
 # Build the images and launch the containers (this will take a while)
-$ docker-compose build
-$ docker-compose up -d
+$ docker compose build
+$ docker compose up -d  
 ```
 
-When testing your changes, include the `--build` flag to see your changes propagate into the containers:
+When testing subsequent changes, you can do this in one step by including the `--build` flag:
 
 ```
-docker-compose up --build -d
+docker compose up --build -d
 ```
 
-After the building process completes (10 to 30 minutes), the site should be available on http://localhost:8000/ in your host machine.
+After the build process completes, the site should be available on http://localhost:8000/ in your host machine.
 
 By default, Cantus Ultimus works in the following way:
 
 ```mermaid
 stateDiagram-v2
-[*] --> nginx: Any HTTP request
+[*] --> nginx: Any request to port 8000
 nginx --> StaticFile: Serve static files directly
 nginx --> gunicorn: Forward webapp requests to port 8001
 gunicorn --> django: Serve content from webapp
 django --> postgres: Use as default database backend
 django --> solr: Bind django database "signals" to solr
 ```
 
-#### Enabling live changes with django's `runserver`
 
-During development, it is often useful to replace `gunicorn` with the default `django` web server, so that modifying the source code results in live changes in the website. This is done by default in `django-config.sh`. If you need to test `gunicorn` during development, edit the if statement in this file.
+### Database migrations
+
+Whenever changes are made to database models, they need to be applied to the PostgreSQL database. This occurs through Django's migrations.
+
+If, during development, you make a change to any models, build and run the containers, as above. Then, enter the command line in the `app` container:
+
+```sh
+$ docker compose exec -it app bash
+```
+
+Then, run the `makemigrations` command:
+
+```sh
+$ python manage.py makemigrations
+```
+
+Migrations will then be created in the `./app/public/cantusdata/migrations/` folder. Commit these migrations and include in the pull request that includes the model changes. 
+
+You will also need to apply these migrations to the database to your development database and, once these model changes are deployed to servers, to staging, production, and any other remote databases. To apply the changes, enter the command line in the `app` container as before and run the `migrate` command:
+
+```sh
+$ python manage.py migrate
+```
+
+Note that migrations will also need to be applied to a newly instantiated database using the `migrate` command.
 
 ### Launch in production
 
-From the Compute Canada VM, follow the same instructions as above, only replace `docker-compose` with `docker compose` and make sure to keep `PORT=80` in the `.env` file.
+From the Compute Canada VM, follow the same instructions as above, making sure `DEVELOPMENT=False` is in the `.env` file.
 
-## Initialize a newly launched website
+## Initialize a newly launched website (for development or deployment)
 
-A freshly initialized instance of the website does not have an admin account. Addititionally, the databases of Manuscripts, Chants, and Folios are not populated.
+A freshly initialized instance of the website does not have an admin account or any data in the database.
 
 A few commands will create an admin account and populate the database.
 
@@ -100,13 +125,15 @@ Password (again):
 Superuser created successfully.
 ```
 
-Using your admin credentials, verify that you are able to log into the admin django site, which should be located in http://localhost:8000/admin/
+Using your admin credentials, verify that you are able to log into the admin django site, which should be located at `/admin/`. 
 
 ![image](https://user-images.githubusercontent.com/7258463/101060564-8be1e500-355d-11eb-887f-5af65b50ba13.png)
 
+When initializing the site, remember to apply migrations to the database (see )
+
 When navigating through any of the tables in the admin interface (e.g., Manuscripts,  and Chants), they will appear to be empty.
 
-We can pre-populate the Manuscripts and Chants from the information available in the [Cantus Database](https://cantusdatabase.org/).
+We can populate the Manuscripts and Chants from the information available in the [Cantus Database](https://cantusdatabase.org/).
 
 The scripts to populate the database are included in the repository. Head back to the terminal where you created the admin user account.
 
@@ -134,7 +161,8 @@ An additional command is included to import chants associated with a specific ma
 ```sh
 $ docker-compose exec app python manage.py import_data chants --manuscript-id MANUSCRIPT_ID
 ```
-however, this process can already be done using the user interface. We recommend using the user interface from this point onward.
+
+This process can also be done using the user interface (recommended; see below).
 
 ## Adding manuscripts and chants using the admin user interface
 

app/django-config.sh

@@ -1,11 +1,9 @@
 #!/bin/bash
 
-python manage.py makemigrations
-python manage.py migrate &
 python manage.py clear_session_data
 
-if [[ $APP_PORT = 80 ]]; then
-    gunicorn -b 0:8001 cantusdata.wsgi --timeout 600 --workers 4
-else
+if [[ $DEVELOPMENT == "True" ]]; then
     python manage.py runserver_plus 0:8001
+else
+    gunicorn -b 0:8001 cantusdata.wsgi --timeout 600 --workers 4
 fi

app/public/cantusdata/settings.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 import os
 
-is_development = os.environ.get("APP_PORT") == "8000"
+is_development = os.environ.get("DEVELOPMENT")
 is_production = not is_development
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.

docker-compose.yaml

@@ -13,7 +13,7 @@ services:
         condition: service_started
     environment:
       - APP_VERSION=${APP_VERSION}
-      - APP_PORT=${PORT}
+      - DEVELOPMENT=${DEVELOPMENT}
       - POSTGRES_DB=${POSTGRES_DB}
       - POSTGRES_USER=${POSTGRES_USER}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
@@ -41,7 +41,7 @@ services:
     container_name: cantus-nginx-1
     build: ./nginx
     ports:
-      - "${PORT}:80"
+      - "8000:8000"
     depends_on:
       - app
 
@@ -86,7 +86,7 @@ services:
       ]
     environment:
       - APP_VERSION=${APP_VERSION}
-      - APP_PORT=${PORT}
+      - DEVELOPMENT=${DEVELOPMENT}
       - POSTGRES_DB=${POSTGRES_DB}
       - POSTGRES_USER=${POSTGRES_USER}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

nginx/nginx.conf

@@ -32,18 +32,18 @@ http {
 
   server {
     # if no Host match, close the connection to prevent host spoofing
-    listen 80 default_server;
+    listen 8000 default_server;
     return 444;
   }
 
   server {
     # use 'listen 80 deferred;' for Linux
     # use 'listen 80 accept_filter=httpready;' for FreeBSD
-    listen 80;
+    listen 8000;
     client_max_body_size 4G;
 
     # set the correct host(s) for your site
-    server_name cantus.simssa.ca cantus.staging.simssa.ca dev-cantus.simssa.ca localhost
+    server_name cantus.simssa.ca cantus.staging.simssa.ca dev-cantus.simssa.ca localhost;
 
     keepalive_timeout 5;