Test docker-compose local deploy configuration

[griff-rees]

Below are instructions for testing a local deploy of the docker-compose branch.

Note: I've moved pyproject.toml into the metadata folder to ease this deploy.

This should be deployable for anyone with docker installed locally. If you use brew on macOS I'd recommend:

$ brew install --cask docker

I'm afraid I haven't tried this on any other operating system yet but there's decent documentation for installing docker desktop. You can try the command line interface but I've had issues with that myself.

Assuming you have docker installed locally, opening a console and getting to your local checkout folder of lib_metadat_db and then entering the metadata folder should be enough to test a build:

$ cd metadata  # the django app and docker-compose script are in the metadata folder
$ docker-compose -f local.yml build

This can take some time, but after the first build components get cached so subsequent builds are usually quicker.

If you make changes to code (ie. pulls from the repo etc.), usually build suffices to apply those to the docker images but if not you may need to force a full rebuild:

$ docker-compose -f local.yml build --no-cache

I have had situations where that didn't quite fix everything, and had to specifically remove a docker volume. Can explain those edge cases in some detail if needed.

Assuming the build is ok, you should be able to deploy locally via

$ docker-compose -f local.yml up

which will then log the process of django starting, postgresql starting and then any new database migrations.

Note: My local metadata/static folder is not included in this commit, and there's a chance that prevents a deploy. Great to know if that happens, in which case it's not hard for me to add. I've tired to minimize this commit as much as possible.

If you see this warning

metadata_local_node      | [15:01:15] Error: File not found with singular glob: /app/metadata/static/sass/project.scss (if this was purposeful, use `allowEmpty` option)

the rest of the deploy should be ok. It relates to a feature I thought of using but not needed (can explain in more detail).

If you see this in the console:

metadata_local_django    | PostgreSQL is available
metadata_local_django    | Operations to perform:
metadata_local_django    |   Apply all migrations: admin, auth, census, contenttypes, gazetteer, mitchells, newspapers, sessions
metadata_local_django    | Running migrations:
metadata_local_django    |   No migrations to apply.
metadata_local_django    | Watching for file changes with StatReloader
metadata_local_django    | Performing system checks...
metadata_local_django    |
metadata_local_django    | System check identified no issues (0 silenced).
metadata_local_django    | October 20, 2022 - 16:05:36
metadata_local_django    | Django version 4.1.2, using settings 'metadata.settings'
metadata_local_django    | Starting development server at http://0.0.0.0:8000/
metadata_local_django    | Quit the server with CONTROL-C.

that indicates the deploy worked! If so, you should be able to go to http://0.0.0.0:8000/ within a web browser and see the default splash page:

To shutdown (gracefully):

$ docker-compose -f local.yml down

Assuming you have the app up you can try: http://0.0.0.0:8000/admin to see the default login for the backend. You'll need to create an admin priviledge account to login. A quick way to create and admin account, and a demonstration for how to run commands within docker containers, is:

$ docker-compose -f local.yml run --rm django python manage.py createsuperuser

That should run the createsuperuser command within your local django docker image instance. You can do this by leaving the server running in one terminal and run that line in a separate terminal (should works if you've run docker-compose -f local.yml down as well).

Once that superuser (admin priviledges) account is created, that should then allow you to login to the backend admin interface, which initially would only show you options for managing Users and Groups like

But: it's quite easy to add access to all the compoenents of the backend tables for management, which would look like:

Note: the automatic plurals of "countrys" can be fixed ;).

Comments, questions etc. much appreciated (and thanks for reading all of this!).

[kallewesterling]

Oh, I didn't see this until today @griff-rees! This is great documentation, thank you!!

[kallewesterling]

Should we make a PR from this into the main branch, @griff-rees? That makes sense, right?

[griff-rees]

If you like, though my first worry is the shift of the placement of pyproject.toml and poetry.lock. Is that going to break the way you're working at the moment?

[kallewesterling]

Hm, good observation. I didn't see that they had moved in the docker branch... Is that because the Dockerfile can't reach the file if it's outside of the directory? I don't know how Docker works well enough to understand the reason why it needs to be there (or whether it'll break my current workflow).

[griff-rees]

Yeah it's a recurring topic of inconvenience with Docker deploy: https://stackoverflow.com/questions/24537340/docker-adding-a-file-from-a-parent-directory

Thinking this can be closed now...

[griff-rees]

Full deploy as of 7fa6f6d. Finished testing locally in 699a063