Create a better Readme

README.md

@@ -6,7 +6,7 @@ Create the virtual environment, enable it, and install the dependencies.
 ```shell
 $ python3 -m venv env
 $ source env/bin/activate
-(env) $ pip install -r requirements.txt
+(env) $ pip install -r docker/prod/requirements.prod.txt
 ```
 
 ## Local settings
@@ -15,11 +15,17 @@ You'll need to copy the `app/local_settings.example.py` file to `app/local_setti
 $ cp app/local_settings.example.py app/local_settings.py
 ```
 
+## stack.env
+The stack.env file referenced is a Portainer special. This is where Portainer would put a file containing all the environment variables set up in its UI.
+To run it manually, you will need to copy `stack.env.example` to `stack.env` in the project root.
+
 ## Running database migrations
 Now we need to run the database migrations in order to get a working database.
 ```shell
 (env) $ python manage.py migrate
 ```
+Note that these are automatically run by a step in the compose file in production.
+You won't need to do that manually.
 
 ## Creating a superuser
 In order to access Django admin, we need a superuser.
@@ -32,28 +38,27 @@ Password (again):
 Superuser created successfully.
 ```
 
-## Running the server
+## Running
-```shell
+The Docker Compose file is located in `docker/docker-compose.prod.yml`.
-(env) $ python manage.py runserver 8001
+There is a shortcut to run it: `make run`.
-Starting development server at http://127.0.0.1:8001/
-Quit the server with CONTROL-C.
-```
-As you've guessed, you can access it at http://127.0.0.1:8001/
 
-## Troubleshooting
+## Stopping
-Sometimes Django is difficult.
+To stop the containers, run `make stop`.
 
-> `django.db.utils.OperationalError: no such table: core_user`
+## Setup
+This setup may be different from what you've seen before.
 
-This means you haven't yet run the migrations. See above.
+### Uvicorn
+There is a Uvicorn worker in the `app` container listening on `/var/run/socks/app.sock`. This is the bit that runs the actual code.
 
-### Updating the models
+### Nginx
-If you make changes to the database models, you will need to create new migrations.
+Nginx runs in the `nginx` container and proxies requests to Uvicorn thanks to a mounted and shared directory. No TCP required.
-Do this like so:
+
-```shell
+### Pre-start steps
-(env) $ python manage.py makemigrations
+There's a few commands running before start to ensure Django works correctly.
-```
+
-Afterwards, we can apply them as normal.
+#### Migration
-```shell
+The `migration` container step runs the migrations so you don't need to remember to do it.
-(env) $ python manage.py migrate
+
-```
+#### Collectstatic
+The `collectstatic` container step collects all static files from plugins and puts them in the `core/static` folder. This folder is served straight from Nginx without going through Uvicorn.