diff --git a/.gitignore b/.gitignore index 92d95da0f..3ccc04fff 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,7 @@ /dist /dj18/ /docs/build/ -/docs/source/_files/docker-compose.yml +/docs/source/_files/compose.yaml /docs/source/_files/openapi.json /fab.conf /include/ diff --git a/docker-compose.yml b/compose.yaml similarity index 100% rename from docker-compose.yml rename to compose.yaml diff --git a/devscripts/files/Dockerfile.certbot b/devscripts/files/Dockerfile.certbot index b91dd0594..0d77e887e 100644 --- a/devscripts/files/Dockerfile.certbot +++ b/devscripts/files/Dockerfile.certbot @@ -12,7 +12,7 @@ ADD devscripts/files/django-ca-test-validation.sh /usr/local/bin/ ADD devscripts/files/django-ca-dns-auth.py /usr/local/bin/django-ca-dns-auth ADD devscripts/files/django-ca-dns-clean.py /usr/local/bin/django-ca-dns-clean -env DNSMASQ_CONF_DIR=/etc/dnsmasq.d/ +ENV DNSMASQ_CONF_DIR=/etc/dnsmasq.d/ WORKDIR /root/ ENTRYPOINT ["/usr/local/bin/dnsmasq.sh"] diff --git a/devscripts/files/docker-compose.certbot.yaml b/devscripts/files/compose.certbot.yaml similarity index 100% rename from devscripts/files/docker-compose.certbot.yaml rename to devscripts/files/compose.certbot.yaml diff --git a/devscripts/validation/docker_compose.py b/devscripts/validation/docker_compose.py index 5d02c4b6d..95d80e079 100644 --- a/devscripts/validation/docker_compose.py +++ b/devscripts/validation/docker_compose.py @@ -378,7 +378,7 @@ def test_tutorial(release: str) -> int: # pylint: disable=too-many-locals # no _validate_crl_ocsp("root.pem", f"{cert_subject}.pem", cert_subject) # Test all endpoints - validate_endpoints("https://localhost", 'user', 'nopass', verify=str(ca_pub_pem)) + validate_endpoints("https://localhost", "user", "nopass", verify=str(ca_pub_pem)) # Finally some manual testing info( @@ -444,6 +444,9 @@ def test_update(release: str) -> int: # Start previous version info(f"Start previous version ({last_release}).") with _compose_up(remove_volumes=False, env=dict(os.environ, DJANGO_CA_VERSION=last_release)): + # Make sure old containers started properly + compose_status() + # Make sure we have started the right version _validate_container_versions(last_release) @@ -467,7 +470,7 @@ def test_update(release: str) -> int: _validate_crl_ocsp("ca.pem", "cert.pem", f"cert.{ca_subject}") old_postgres_version = get_postgres_version("docker-compose.yml") - new_postgres_version = get_postgres_version(config.ROOT_DIR / "docker-compose.yml") + new_postgres_version = get_postgres_version(config.ROOT_DIR / "compose.yaml") # Backup database if there was a PostgreSQL update if old_postgres_version != new_postgres_version: @@ -482,9 +485,17 @@ def test_update(release: str) -> int: env={"DJANGO_CA_VERSION": release}, stdout=stream, ) - # copy new docker-compose file - shutil.copy(config.ROOT_DIR / "docker-compose.yml", tmpdir) - ok("Updated docker-compose.yml") + # Copy new Docker Compose file + shutil.copy(config.ROOT_DIR / "compose.yaml", tmpdir) + ok("Updated compose.yaml") + + # Remove legacy Docker Compose configuration file + docker_compose_yml = Path(tmpdir) / "docker-compose.yml" + if docker_compose_yml.exists(): + os.remove(docker_compose_yml) + else: + # Remind us in the next version that the old config file does not exist anymore. + info(f"{docker_compose_yml}: File does not exist, you can remove this part of the code.") # Apply backup if there was a PostreSQL update if old_postgres_version != new_postgres_version: @@ -515,6 +526,9 @@ def test_update(release: str) -> int: # Start and check new version info(f"Start current version ({release}).") with _compose_up(env=dict(os.environ, DJANGO_CA_VERSION=release)): + # Make sure containers started properly + compose_status() + # Make sure we have the new version _validate_container_versions(release) @@ -536,8 +550,8 @@ def test_acme(release: str, image: str) -> int: """Test ACMEv2 validation.""" info(f"Validating ACMVEv2 implementation on {image}...") - compose_override = config.DEVSCRIPTS_FILES / "docker-compose.certbot.yaml" - compose_files = f"docker-compose.yml:{compose_override}" + compose_override = config.DEVSCRIPTS_FILES / "compose.certbot.yaml" + compose_files = f"compose.yaml:{compose_override}" environ = dict(os.environ, COMPOSE_FILE=compose_files, DJANGO_CA_VERSION=release) errors = 0 diff --git a/docs/Makefile b/docs/Makefile index 55f8b5935..2a85ac30f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -14,13 +14,13 @@ help: .PHONY: help Makefile source/_files/docker-compose.yml source/_files/openapi.json extra-files -source/_files/docker-compose.yml: - cp ../docker-compose.yml source/_files/ +source/_files/compose.yaml: + cp ../compose.yaml source/_files/ source/_files/openapi.json: DJANGO_SETTINGS_MODULE=ca.test_settings python ../ca/manage.py export_openapi_schema --api django_ca.api.endpoints.api > source/_files/openapi.json -extra-files: source/_files/openapi.json source/_files/docker-compose.yml +extra-files: source/_files/openapi.json source/_files/compose.yaml # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/source/include/quickstart_with_docker_compose/docker-compose.override.yml.jinja b/docs/source/include/quickstart_with_docker_compose/compose.override.yaml.jinja similarity index 100% rename from docs/source/include/quickstart_with_docker_compose/docker-compose.override.yml.jinja rename to docs/source/include/quickstart_with_docker_compose/compose.override.yaml.jinja diff --git a/docs/source/quickstart/docker_compose.rst b/docs/source/quickstart/docker_compose.rst index 595c0ad6c..161be0b1a 100644 --- a/docs/source/quickstart/docker_compose.rst +++ b/docs/source/quickstart/docker_compose.rst @@ -22,7 +22,7 @@ This tutorial will give you a CA with Required software ================= -To run **django-ca**, you need Docker (at least version 19.03.0) and Docker Compose (at least version 1.27.0). +To run **django-ca**, you need Docker (at least version 19.03.0) and Docker Compose (at least version 1.28.0). You also need certbot to acquire Let's Encrypt certificates for the admin interface. OpenSSL is used to generate the DH parameter file. On Debian/Ubuntu, simply do: @@ -64,9 +64,9 @@ To run **django-ca**, you'll need a couple of files: * `dhparam.pem `_, the DH parameters (required for TLS connections). * `localsettings.yaml `_, the configuration for **django-ca**. -* `docker-compose.yml `_, the configuration for Docker Compose. -* `docker-compose.override.yml `_, system-local - configuration overrides for Docker Compose. +* `compose.yaml `_, the configuration for Docker Compose. +* `compose.override.yaml `_, system-local configuration + overrides for Docker Compose. * `.env `_, the environment file for Docker Compose. Read the sections below how to retrieve or generate all these files. @@ -120,12 +120,12 @@ Environment variables --------------------- If you want to use environment variables for configuration, we recommend you first add them to your -``docker-compose.override.yml``, for example to `configure a different SMTP server +``compose.override.yaml``, for example to `configure a different SMTP server `_ for sending out emails: .. literalinclude:: /include/quickstart_with_docker_compose/docker-compose.override-env-example.yml :language: yaml - :caption: docker-compose.override.yml + :caption: compose.override.yaml and in your `.env `_ file, set the variable: @@ -133,14 +133,14 @@ and in your `.env `_ file, set the variable: DJANGO_CA_EMAIL_HOST=smtp.example.com -.. _quickstart-docker-compose-docker-compose.yml: +.. _quickstart-docker-compose-compose.yaml: -Add ``docker-compose.yml`` -========================== +Add ``compose.yaml`` +==================== -Docker-compose needs a configuration file, :download:`docker-compose.yml `. You +Docker-compose needs a configuration file, :download:`compose.yaml `. You can also download the file for other versions `from github -`_. +`_. You can also get versions for specific versions of **django-ca** from the table below, which also shows bundled third-party Docker images. @@ -165,23 +165,23 @@ Version `1.23.0 `_ 7 12 **1.23** ==================================================================================== ===== ========== ======= -.. _quickstart-docker-compose-docker-compose.override.yml: +Note that until ``django-ca==2.1.1``, this file was called ``docker-compose.yml``. -Add ``docker-compose.override.yml`` -=================================== +.. _quickstart-docker-compose-compose.override.yaml: -The default :file:`docker-compose.yml` does not offer HTTPS, because too many details (cert location, etc.) +Add ``compose.override.yaml`` +============================= + +The default :file:`compose.yaml` does not offer HTTPS, because too many details (cert location, etc.) are different from system to system. We need to add a `docker-compose override file -`_ to open the port and map the directories with the certificates -into the container. Simply add a file called :file:`docker-compose.override.yml` next to your main -configuration file: +`_ to open the port and map the +directories with the certificates into the container. Simply add a file called :file:`compose.override.yaml` +next to your main configuration file: -.. template-include:: yaml /include/quickstart_with_docker_compose/docker-compose.override.yml.jinja - :caption: docker-compose.override.yml +.. template-include:: yaml /include/quickstart_with_docker_compose/compose.override.yaml.jinja + :caption: compose.override.yaml :context: quickstart-with-docker-compose -In the above example, we already add - This will work if you get your certificates using ``certbot`` or a similar client. If your private key in public key chain is named different, you can set ``NGINX_PRIVATE_KEY`` and ``NGINX_PUBLIC_KEY`` in your :file:`.env` file below. @@ -192,7 +192,7 @@ Add ``.env`` file ================= Some settings in **django-ca** can be configured with environment variables (except where a more complex -structure is required). Simply create a file called :file:`.env` next to :file:`docker-compose.yaml`. +structure is required). Simply create a file called :file:`.env` next to :file:`compose.yaml`. For a quick start, there are only a few variables you need to specify: @@ -203,12 +203,12 @@ For a quick start, there are only a few variables you need to specify: Recap ===== -By now, you should have at least **five** files in ``~/ca/``: +By now, you should have **five** files in ``~/ca/``: .. code-block:: console user@host:~/ca/$ ls -A - docker-compose.yml docker-compose.override.yml .env dhparam.pem localsettings.yaml + compose.yaml compose.override.yaml .env dhparam.pem localsettings.yaml ************* Start your CA @@ -307,12 +307,12 @@ Update Remember to :ref:`backup your data ` before you perform any update. -In general, updating django-ca is done by getting the :ref:`latest version of docker-compose.yml -` and then simply recreating the containers: +In general, updating django-ca is done by getting the :ref:`latest version of compose.yaml +` and then simply recreating the containers: .. code-block:: console - user@host:~/ca/$ curl -O https://.../docker-compose.yml + user@host:~/ca/$ curl -O https://.../compose.yaml user@host:~/ca/$ docker compose up -d .. _postgresql_update: @@ -320,7 +320,7 @@ In general, updating django-ca is done by getting the :ref:`latest version of do PostgreSQL update ================= -When a new version :file:`docker-compose.yml` includes a new version of PostgreSQL, you have to take some +When a new version :file:`compose.yaml` includes a new version of PostgreSQL, you have to take some extra steps to migrate the PostgreSQL database. **Before you upgrade**, back up your PostgreSQL database as usual: @@ -331,11 +331,11 @@ extra steps to migrate the PostgreSQL database. user@host:~/ca/$ docker compose up -d db user@host:~/ca/$ docker compose exec db pg_dump -U postgres -d postgres > backup.sql -Now update :file:`docker-compose.yml` but then **only start the database**: +Now update :file:`compose.yaml` but then **only start the database**: .. code-block:: console - user@host:~/ca/$ curl -O https://.../docker-compose.yml + user@host:~/ca/$ curl -O https://.../compose.yaml user@host:~/ca/$ docker compose up -d db Once the database is started, update the database with data from your backup and normally start your setup: @@ -349,5 +349,5 @@ Forgot to backup? ----------------- If you forgot to backup your database and started the update already, don't panic. Whenever we update the -PostgreSQL version, we use a a new Docker volume. You should be able to reset :file:`docker-compose.yml` and +PostgreSQL version, we use a a new Docker volume. You should be able to reset :file:`compose.yaml` and then proceed to do the backup normally. diff --git a/docs/source/update.rst b/docs/source/update.rst index a656e6073..654f56781 100644 --- a/docs/source/update.rst +++ b/docs/source/update.rst @@ -303,7 +303,7 @@ Note that if you have stored private keys in any custom location with the ``--pa backup these locations as well. **Second,** update your :file:`docker-compose.yml` file. Either get the :ref:`latest version of the file -`, or apply this diff: +`, or apply this diff: .. code-block:: diff