From 43a35ee5fd958b5e278f2e452780664357636369 Mon Sep 17 00:00:00 2001 From: John Martinez Date: Tue, 19 Sep 2023 17:24:32 +0000 Subject: [PATCH 1/6] A more newbie-friendly Docker HOWTO --- docs/docker.md | 125 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 107 insertions(+), 18 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 62ec45ca..8a32fe4f 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -2,43 +2,132 @@ There is now an official [uMap](https://hub.docker.com/r/umap/umap) image. -To run it with docker compose, use a `docker-compose.yml` like this: +To run it with docker compose, create a `docker-compose.yml` like this: +_Sample docker-compose.yml_ ```yaml version: '3' services: db: - image: postgis/postgis:14-3.3-alpine + # check https://hub.docker.com/r/postgis/postgis to see available versions + image: postgis/postgis:14-3.4-alpine environment: - POSTGRES_HOST_AUTH_METHOD=trust volumes: - - db:/var/lib/postgresql/data + - umap_db:/var/lib/postgresql/data app: - image: umap/umap:x.x.x + # Check https://hub.docker.com/r/umap/umap/tags to find the latest version + image: umap/umap:1.3.7 ports: + # modify the external port (8001, on the left) if desired, but make sure it matches SITE_URL, below - "8001:8000" environment: - DATABASE_URL=postgis://postgres@db/postgres - - SECRET_KEY=some-long-and-weirdly-unrandom-secret-key - - SITE_URL=https://umap.local/ - - UMAP_ALLOW_ANONYMOUS=True - - DEBUG=1 + - SITE_URL=https://localhost:8001/ + - STATIC_ROOT=/srv/umap/static + - MEDIA_ROOT=/srv/umap/uploads volumes: - - data:/srv/umap/uploads - + - umap_userdata:/srv/umap/uploads + # FIX the path on the left, below, to your location + - /home/ubuntu/umap.conf:/etc/umap/umap.conf + restart: always + depends_on: + - db + volumes: - data: - db: + umap_userdata: + umap_db: + ``` +next, create a basic settings file, named `umap.conf`` in the same directory. + +You can use this example below and it will run, but you may want to look at the project sample config, using `wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf` and modify as needed. + +Make sure the settings in the docker-compose don't conflict with the sample config and vice-versa. In particular, remove the DATABASES section from the config file if useing the docker-compose file, or it will override the DATABASE_URL setting and things won't work. + +_Sample umap.conf_ +```python +""" +Example settings for docker quickstart: +Lots of stuff has been removed for simplicity + +See https://umap-project.readthedocs.io/en/master/settings/ + +Things YOU need to change before launching: +- modify SECRET_KEY +""" + +from umap.settings.base import * # pylint: disable=W0614,W0401 + +SECRET_KEY = '!!secretsecret!!' +INTERNAL_IPS = ('127.0.0.1', ) +ALLOWED_HOSTS = ['*', ] + +DEBUG = True +COMPRESS_ENABLED = True +COMPRESS_OFFLINE = True +LANGUAGE_CODE = 'en' + +# Set to False if login into django account should not be possible. You can +# administer accounts in the admin interface. +ENABLE_ACCOUNT_LOGIN = True +AUTHENTICATION_BACKENDS = ( + 'django.contrib.auth.backends.ModelBackend', +) + +# Enables a banner letting users know this site is not for production use +UMAP_DEMO_SITE = True + +# Whether to allow non authenticated people to create maps. +UMAP_ALLOW_ANONYMOUS = True +``` + +Some basic settings are available through env vars (see https://github.com/umap-project/umap/blob/master/umap/settings/base.py) and can be defined right in the docker-compose file, +but if you need more custom ones (like custom OAuth configuration), the easiest +way is to put them in a [settings file](settings.md) and mount it to `/etc/umap/umap.conf`. + +--- + +#### Quick sidebar about docker and docker-compose +A multi-platform tutorial on [installing docker](https://docs.docker.com/get-docker/) and docker-compose is outside the scope of this howto, but if you are on a recent Ubuntu, this is all you need to install both: + +```bash +sudo groupadd docker +sudo snap install docker +sudo usermod -aG docker $USER +# EXIT and log back in to pickup the docker group membership, then test with +docker run hello-world +``` + +Current versions of docker compose are integrated into the docker command and launch with `docker compose` (two words) -- older versions use a separate binary named `docker-compose`. Either one will work for this. + +--- + +### Initial launch + +Start the server with +```bash +docker compose up +``` +... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/erros about 'psychopg' being unable to connect. This should sort itself out as the app retries. + ### Create superuser -With docker-compose, run `docker-compose run app /venv/bin/umap createsuperuser` +Now you need to create your site superuser. Stop the server (Ctrl-C) and then type: +```bash +docker-compose run app /venv/bin/umap createsuperuser` +`````` + +Once that's done, you can relaunch your server with `docker compose up` + +### Try It! + +You should not ne able to brose to your uMap instance form a browser on your local system, by pointing your browser to ${SITE_URL} (see the docker-compose file, above.) + +### Administration + +To administer the site (add users, change map tiles, other customizations) log in as the root user you just created, then go to ${SITE_URL}/admin -### Custom settings - -Some basic settings are available through env vars (see https://github.com/umap-project/umap/blob/master/umap/settings/base.py), -but if you need more custom ones (like custom OAuth configuration), the easiest -way is to push a [settings file](settings.md) to `/etc/umap/umap.conf`. From cc9004fbc2aec2eda3237aadf3bbae522aba828d Mon Sep 17 00:00:00 2001 From: John Martinez Date: Tue, 19 Sep 2023 17:43:13 +0000 Subject: [PATCH 2/6] Code review feedback --- docs/docker.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 8a32fe4f..6a53db9f 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -117,14 +117,14 @@ docker compose up Now you need to create your site superuser. Stop the server (Ctrl-C) and then type: ```bash -docker-compose run app /venv/bin/umap createsuperuser` -`````` +docker-compose run app /venv/bin/umap createsuperuser +``` Once that's done, you can relaunch your server with `docker compose up` ### Try It! -You should not ne able to brose to your uMap instance form a browser on your local system, by pointing your browser to ${SITE_URL} (see the docker-compose file, above.) +You should now be able to browse to your uMap instance from a browser on your local system, by pointing your browser to `https://localhost:8001/` (equivalent to `${SITE_URL}` in the docker-compose file, above). ### Administration From 2f21d7b8219bdf91865bba0234d92515b52fb226 Mon Sep 17 00:00:00 2001 From: John Martinez Date: Tue, 19 Sep 2023 14:41:14 -0400 Subject: [PATCH 3/6] Update docs/docker.md punctuation Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com> --- docs/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker.md b/docs/docker.md index 6a53db9f..5683b18a 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -128,6 +128,6 @@ You should now be able to browse to your uMap instance from a browser on your lo ### Administration -To administer the site (add users, change map tiles, other customizations) log in as the root user you just created, then go to ${SITE_URL}/admin +To administer the site (add users, change map tiles, other customizations) log in as the root user you just created, then go to `${SITE_URL}/admin`. From 74fd3f4a667b8e76819e4b502206983b8976affe Mon Sep 17 00:00:00 2001 From: John Martinez Date: Tue, 19 Sep 2023 14:43:51 -0400 Subject: [PATCH 4/6] Update docs/docker.md Typo Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com> --- docs/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker.md b/docs/docker.md index 5683b18a..45d2207e 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -41,7 +41,7 @@ volumes: ``` -next, create a basic settings file, named `umap.conf`` in the same directory. +Next, create a basic settings file, named `umap.conf` in the same directory. You can use this example below and it will run, but you may want to look at the project sample config, using `wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf` and modify as needed. From 93cfe803700906173a736718df0f9119d8b6f69d Mon Sep 17 00:00:00 2001 From: John Martinez Date: Tue, 19 Sep 2023 14:44:31 -0400 Subject: [PATCH 5/6] Update docs/docker.md typo Co-authored-by: David Larlet <3556+davidbgk@users.noreply.github.com> --- docs/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker.md b/docs/docker.md index 45d2207e..36a88ee3 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -111,7 +111,7 @@ Start the server with ```bash docker compose up ``` -... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/erros about 'psychopg' being unable to connect. This should sort itself out as the app retries. +... and let it run some initial setup until the output quiesces with a message about spawning uWSGI workers. Because there is a race between the time the app tries to connect to the DB and when the DB is actually ready, you might see a few exceptions/errors about 'psycopg' being unable to connect. This should sort itself out as the app retries. ### Create superuser From 7e2b20d08520f9a5e933483d146dd3c26b135f88 Mon Sep 17 00:00:00 2001 From: John Martinez Date: Wed, 20 Sep 2023 12:07:58 -0400 Subject: [PATCH 6/6] Update docs/docker.md Co-authored-by: Yohan Boniface --- docs/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker.md b/docs/docker.md index 36a88ee3..08f47e04 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -45,7 +45,7 @@ Next, create a basic settings file, named `umap.conf` in the same directory. You can use this example below and it will run, but you may want to look at the project sample config, using `wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf` and modify as needed. -Make sure the settings in the docker-compose don't conflict with the sample config and vice-versa. In particular, remove the DATABASES section from the config file if useing the docker-compose file, or it will override the DATABASE_URL setting and things won't work. +Make sure the settings in the docker-compose don't conflict with the sample config and vice-versa. In particular, remove the DATABASES section from the config file if using the docker-compose file, or it will override the DATABASE_URL setting and things won't work. _Sample umap.conf_ ```python