Jafner/Jafner.net
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity

Improved documentation for basics of docker

Browse Source
This commit is contained in:
Jafner 2021-07-06 14:40:30 -07:00
parent 5f9db447e7
commit ec2eed76d3
1 changed files with 21 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
5etools-docker/README.md
View File

@ -4,13 +4,23 @@ This is a simple image for hosting your own 5eTools instance. It is based on the
## Quickstart ## Quickstart
You can quick-start this image by running: You can quick-start this image by running:
`docker run -d -p 80:80 --name 5etools-docker jafner/5etools-docker` `docker run -d -p 80:80 --rm --name 5etools-docker jafner/5etools-docker`
Then give the container a minute or two to come online and it will be accessible at `localhost`. Then give the container a minute or two to come online and it will be accessible at `localhost`.
This is what each part of that command does:
```
docker run \ # this is the basic docker command to start a docker container from a given image
-d \ # this is the 'daemon' flag, which allows the container to run in the background
-p 80:80 \ # this is the port flag which maps port 80 on the host to port 80 inside the container. You can change the host port mapping to something else (such as 8080) if you already have something running on port 80.
--rm \ # this is the remove flag, it tells docker to delete the container when it stops running. This is an option for portability.
--name 5etools-docker \ # this tells docker to set the name of the new container to 5etools-docker, rather than auto-generate a name. You can change this to whatever you like.
jafner/5etools-docker # this is the docker image you want to run. jafner is the repository and 5etools-docker is the specific image.
```
## Getting token images ## Getting token images
You can configure the container's initialization script to download image files by setting the `IMG` environment variable: You can configure the container's initialization script to download image files by setting the `IMG` environment variable:
`docker run -d -p 80:80 --name 5etools-docker -e IMG=true 5etools-docker` `docker run -d -p 80:80 --rm --name 5etools-docker -e IMG=true 5etools-docker`
This will add a significant amount of time to the container's initialization. This will add a significant amount of time to the container's initialization.
The `-e` flag specifies a Docker environment variable, which is passed into the container's shell environment and allows for customization of the container during the run command. Here, the environment variable is named `IMG` and this command sets the value to `true`.
## Using a persistent volume ## Using a persistent volume
You can configure the container to use a persistent volume for the server files, either as a Docker-managed volume or by directly mounting a directory on the host file system into the container. Using a persistent volume is required in order to auto-load homebrew. You can configure the container to use a persistent volume for the server files, either as a Docker-managed volume or by directly mounting a directory on the host file system into the container. Using a persistent volume is required in order to auto-load homebrew.
@ -22,17 +32,20 @@ You can persist your container's data by using a Docker-managed volume to preser
### Using a host directory mapping ### Using a host directory mapping
You can alternatively persist your container's data by mapping a directory in the host's file system into the container. To do this, first create two empty directories on the host to map into the container: You can alternatively persist your container's data by mapping a directory in the host's file system into the container. To do this, first create two empty directories on the host to map into the container:
`~/5etools-volume$ mkdir htdocs/ htdocs/download` `~/docker/5etools-docker$ mkdir htdocs/ htdocs/download`
Both of these directories need to be created for the mapping to work. Both of these directories need to be created for the mapping to work.
After you've created the empty directories, you can map them into the container with `-v ~/5etools-volume/htdocs:/usr/local/apache2/htdocs`. After you've created the empty directories, you can map them into the container with `-v ~/5etools-docker/htdocs:/usr/local/apache2/htdocs`.
`docker run -d -p 80:80 --name 5etools-docker -v ~/5etools-volume/htdocs:/usr/local/apache2/htdocs 5etools-docker` `docker run -d -p 80:80 --name 5etools-docker -v ~/docker/5etools-docker/htdocs:/usr/local/apache2/htdocs 5etools-docker`
Note: host directory mappings must be absolute (cannot use `.` to refer to working directory). However, you can still refer to your working directory with `-v ${PWD}/htdocs:/usr/local/apache2/htdocs` where `${PWD}` runs the pwd (print working directory) command and passes it into the mapping.
## Auto-loading homebrew ## Auto-loading homebrew
It is recommended that you use a host directory mapping if you are going to auto-load homebrew, as the tools for copying files into and out of Docker-managed volumes are more limited. Since this container uses the developer version of the 5eTools server files, homebrew auto-loading is enabled by default. You can configure the homebrew auto-loading as described on the [wiki page](https://wiki.5e.tools/index.php/5eTools_Install_Guide). To set up auto-loading homebrew, first create an empty `homebrew/` folder in the directory you would like to use for 5etools-docker. For example `~/docker/5etools-docker/htdocs/homebrew`. Then, run the docker container with `-v ~/docker/5etools-docker/htdocs/homebrew:/usr/local/apache2/htdocs/homebrew`. If you are already using a host directory mapping of `-v ~/docker/5etools-docker/htdocs:/usr/local/apache2/htdocs` then this is unnecessary.
You can configure the homebrew auto-loading as described on the [wiki page](https://wiki.5e.tools/index.php/5eTools_Install_Guide). You will need to download the json files for the homebrew you would like to auto-load and place them into the `homebrew/` directory, then add the filenames to `homebrew/index.json`.
## Updating the container ## Updating the container
Because this image is built on the auto-updater script, updating the container is very simple. Restart the container with `docker restart 5etools-docker`. When it restarts, the container will automatically check for an update and automatically download it before starting. Because this image is built on the auto-updater script, updating the container is very simple. Restart the container with `docker restart 5etools-docker`. When it restarts, the container will automatically check for an update and automatically download it before starting. This is true regardless of whether the container is configured to use a persistent volume.
Note: there is no way to disable this auto-updating behavior except to never restart the container. If you want a specific version of the container, it is recommended that you use the `httpd` image instead.
## Integrating a reverse proxy ## Integrating a reverse proxy
Supporting integration of a reverse proxy is beyond the scope of this guide. Supporting integration of a reverse proxy is beyond the scope of this guide.
However, any instructions which work for the base httpd (Apache) image, should also work for this, as it is minimally different. However, any instructions which work for the base `httpd` (Apache) image, should also work for this, as it is minimally different.