Changes to Docker and Podman documentation

admin/docker.md

@@ -1,22 +1,90 @@
 # 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
+```
+
+Once the changes have been done, you may start the main containers:
+
+```bash
+docker compose --project-name writefreely up --detach
+```
+
+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! 🎉
+
+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.
+
+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:
+
+* 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
+
+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:
 
 ```
-docker-compose up -d
-./docker-setup.sh
+ERROR: 2023/07/31 02:52:02 main.go:120: init keys: open keys/email.aes256: no such file or directory
 ```
 
-Now you should be able to navigate to http://localhost:8080 and start working!
+If you fail to initialize the database, you will see:
 
-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.
+```
+Error 1146: Table 'writefreelydb.collections' doesn't exist.
+```
 
-## Using Docker for Production
+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
+```
 
-WriteFreely doesn't yet provide an official Docker pathway to production. We're working on it, though!
+If your config file contains `open_registration=false` and `single_user=true`, you will see "Page not found".