From 154d05d0212a496a12c8d83fd19d7ca3fba8f73b Mon Sep 17 00:00:00 2001 From: Herzenschein Date: Fri, 6 Oct 2023 17:53:22 -0300 Subject: [PATCH 1/3] Update docker.md This method should be guaranteed to be functional for Docker and Podman --- admin/docker.md | 61 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 10 deletions(-) diff --git a/admin/docker.md b/admin/docker.md index 31870c2..48a909a 100644 --- a/admin/docker.md +++ b/admin/docker.md @@ -1,22 +1,63 @@ # Docker -## Using Docker for Development +## Using docker compose -If you'd like to use Docker as a base for working on a site's styles and such, you can run the following from a Bash shell. +The preferred way to run WriteFreely is by using the provided [docker-compose.yml file](https://github.com/writefreely/writefreely/blob/develop/docker-compose.yml). -*Note: This process is intended only for working on site styling. If you'd like to run Write Freely in production as a Docker service, it'll require a little more work.* +The first step to run WriteFreely is to create the configuration file. It can be copied from the WriteFreely repository to the same folder containing the compose file: -The `docker-setup.sh` script will present you with a few questions to set up your dev instance. You can hit enter for most of them, except for "Admin username" and "Admin password." You'll probably have to wait a few seconds after running `docker-compose up -d` for the Docker services to come up before running the bash script. +```bash +cp config/sample-config.ini config.ini +``` + +Or it can be generated by using the WriteFreely container: + +```bash +touch config.ini +chmod 606 config.ini +docker run --name writefreely --rm --interactive --tty --mount type=bind,source=./config.ini,destination=/go/config.ini,rw,relabel=private docker.io/writeas/writefreely:latest config generate +``` +While running, the container will present you with several questions to set up your configuration file. Once it is complete, the configuration file should be present in your current folder and you should change it to make sure the following settings are correct: + +```ini +bind = 0.0.0.0 +username = writefreely # same as MYSQL_USER in writefreely-db.container +password = writefreelypass # same as MYSQL_PASSWORD in writefreely-db.container +database = writefreelydb # same as MYSQL_DATABASE in writefreely-db.container +hostname = writefreely-db # same as the container service name +single_user = false +open_registration = true ``` -docker-compose up -d -./docker-setup.sh + +Once the changes have been done, you may start the main containers: + +```bash +docker compose --project-name writefreely up --detach ``` -Now you should be able to navigate to http://localhost:8080 and start working! +The MariaDB container should be running, but not WriteFreely yet. You will need to initialize the database using a disposable WriteFreely container connecting to the database: + +```bash +docker run --network writefreely_writefreely --name writefreely --rm --interactive --tty --mount type=bind,source=./config.ini,destination=/go/config.ini,rw docker.io/writeas/writefreely:latest db init +``` + +After that, simply start the WriteFreely container: + +```bash +docker start writefreely-web +``` + +Congratulations, your WriteFreely instance should be running under http://localhost:8080! 🎉 + +## Using podman compose + +The compose file follows best practices for SELinux flags such that it should run correctly under podman compose using the same instructions provided for docker compose. -When you're completely done working, you can run `docker-compose down` to destroy your virtual environment, including your database data. Otherwise, `docker-compose stop` will shut down your environment without destroying your data. +The main differences here are that the use of Docker Networks is not required except for initializing the database, and you may instead use Kubernetes Pods instead. In other words: -## Using Docker for Production +* You don't need to use `networks:` in the compose file +* You can run `podman-compose --project-name writefreely --in-pod 1 up --detach` to raise the containers under a pod +* You can run `podman run --pod pod_writefreely --network writefreely_writefreely --name writefreely --rm --interactive --tty --mount type=bind,source=./config.ini,destination=/go/config.ini,rw docker.io/writeas/writefreely:latest db init` to initialize the database while in a pod -WriteFreely doesn't yet provide an official Docker pathway to production. We're working on it, though! +Once your containers are running, you may then generate systemd service files using [podman-generate-systemd](https://docs.podman.io/en/latest/markdown/podman-generate-systemd.1.html), generate a Kubernetes Deployment using [podman-kube-generate](https://docs.podman.io/en/latest/markdown/podman-kube-generate.1.html), or even better, use [Podman Quadlets](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) instead of compose files for easy integration with systemd. From 98efeedcf8462d19fa13570871535296b1c1280d Mon Sep 17 00:00:00 2001 From: Herzenschein Date: Fri, 6 Oct 2023 17:55:04 -0300 Subject: [PATCH 2/3] Mention that the first user is admin --- admin/docker.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/admin/docker.md b/admin/docker.md index 48a909a..f96e2de 100644 --- a/admin/docker.md +++ b/admin/docker.md @@ -50,6 +50,8 @@ docker start writefreely-web Congratulations, your WriteFreely instance should be running under http://localhost:8080! 🎉 +Remember that the first user to register in your instance will be the admin user. + ## Using podman compose The compose file follows best practices for SELinux flags such that it should run correctly under podman compose using the same instructions provided for docker compose. From ac2124ba78b85cf424dc9e4569951ad09896bcb3 Mon Sep 17 00:00:00 2001 From: Herzenschein Date: Fri, 6 Oct 2023 17:56:29 -0300 Subject: [PATCH 3/3] Add troubleshooting section --- admin/docker.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/admin/docker.md b/admin/docker.md index f96e2de..46ee9f6 100644 --- a/admin/docker.md +++ b/admin/docker.md @@ -63,3 +63,28 @@ The main differences here are that the use of Docker Networks is not required ex * You can run `podman run --pod pod_writefreely --network writefreely_writefreely --name writefreely --rm --interactive --tty --mount type=bind,source=./config.ini,destination=/go/config.ini,rw docker.io/writeas/writefreely:latest db init` to initialize the database while in a pod Once your containers are running, you may then generate systemd service files using [podman-generate-systemd](https://docs.podman.io/en/latest/markdown/podman-generate-systemd.1.html), generate a Kubernetes Deployment using [podman-kube-generate](https://docs.podman.io/en/latest/markdown/podman-kube-generate.1.html), or even better, use [Podman Quadlets](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) instead of compose files for easy integration with systemd. + +## Troubleshooting container issues + +WriteFreely will attempt to generate keys if you do not provide your own with +`writefreely generate keys`. If you fail to mount the volume correctly, you will see: + +``` +ERROR: 2023/07/31 02:52:02 main.go:120: init keys: open keys/email.aes256: no such file or directory +``` + +If you fail to initialize the database, you will see: + +``` +Error 1146: Table 'writefreelydb.collections' doesn't exist. +``` + +You should use 0.0.0.0 as your bind in the configuration file. Otherwise, +you will see: + +``` +curl http://localhost:8080 +curl: (56) Recv failure: Connection reset by peer +``` + +If your config file contains `open_registration=false` and `single_user=true`, you will see "Page not found".