dahjah/5etools-docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure and polish readme

Browse Source
This commit is contained in:
Jafner 2021-08-01 15:10:27 -07:00
parent a2dc60552f
commit 842aae3da7
1 changed files with 27 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -1,4 +1,4 @@
This is a simple image for hosting your own 5eTools instance. It is based on the Apache `httpd` image and uses a modified version of the auto-updater script from the [5eTools wiki](https://wiki.5e.tools/index.php/5eTools_Install_Guide).
This is a simple image for hosting your own 5eTools instance. It is based on the Apache `httpd` image and uses a heavily-modified version of the auto-updater script from the [5eTools wiki](https://wiki.5e.tools/index.php/5eTools_Install_Guide).
# Usage with Docker Run
@ -10,79 +10,57 @@ When you stop the container, it will automatically delete itself, but the downlo
### Getting token images
You can configure the container's initialization script to download image files by setting the `IMG` environment variable:
`docker run -d -p 80:80 --rm --name 5etools-docker -e IMG=true 5etools-docker`
`docker run -d -p 80:80 --rm --name 5etools-docker -v 5etools:/usr/local/apache2/htdocs -e IMG=true jafner/5etools-docker`
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
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.
#### Using a Docker-managed volume
You can persist your container's data by using a Docker-managed volume to preserve data, even if the container is destroyed. To do this, add `-v 5etools_vol:/usr/local/apache2/htdocs` to your run command.
`docker run -d -p 80:80 --name 5etools-docker -v 5etools_vol:/usr/local/apache2/htdocs`
By default, this container uses a Docker-managed persistent volume for the server files. This saves allows the downloaded 5eTools files to persist, even if the container is destroyed. Alternatively, you can use a host directory mapping to share files between you host filesystem and the container.
#### 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:
`~/docker/5etools-docker$ mkdir htdocs/ htdocs/download`
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-docker/htdocs:/usr/local/apache2/htdocs`.
`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.
You can alternatively persist your container's data by mapping a directory in the host's file system into the container. Assuming you want to use the directory `~/5etools-docker` on the host:
### Auto-loading homebrew
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`.
1. Create the directories with `mkdir ~/5etools-docker ~/5etools-docker/htdocs ~/5etools-docker/htdocs/download`. All of these directories need to be created for the mapping to work.
2. Run the container with `docker run -d -p 80:80 --rm --name 5etools-docker -v ~/5etools-docker/htdocs:/usr/local/apache2/htdocs`
Note: host directory mappings must be absolute (cannot use `.` to refer to working directory). However, you can still refer to your working directory with `${PWD}`.
### 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. 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.
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 download it before starting.
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 look into using the `httpd` image instead.
### Integrating a reverse proxy
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.
# Usage with Docker Compose
Create a `docker-compose.yml` file with the following contents:
Create the `~/5etools-docker/docker-compose.yml` file with your preferred text editor. Then add the following contents:
```yml
version: '3'
services:
5etools:
image: jafner/5etools-docker
container_name: 5etools
container_name: 5etools-docker
volumes:
- 5etools_vol:/usr/local/apache2/htdocs
# to switch from a Docker-managed volume to a host directory mapping,
# comment out the "- 5etools:..." line,
# and uncomment the "- ~/5etools-docker/htdocs:..." line
# make sure the ~/5etools-docker/htdocs/download folder exists before onlining the stack
- 5etools:/usr/local/apache2/htdocs # comment this line
#- ~/5etools-docker/htdocs:/usr/local/apache2/htdocs # uncomment this line
ports:
- 8080:80
- 80:80
volumes:
5etools_vol:
```
This version has a persistent Docker-managed volume. If you would like to auto-load homebrew, see the section below.
## Docker Compose with auto-loading homebrew
You will need to do a little prep on your host before starting the Docker Compose stack.
Assuming you want to use the directory `~/5etools-docker` on the host:
1. Create the directories with `mkdir ~/5etools-docker ~/5etools-docker/htdocs ~/5etools-docker/htdocs/download`.
2. Create the `~/5etools-docker/docker-compose.yml` file with your preferred text editor.
3. Add the following contents:
```yml
version: '3'
services:
5etools:
image: jafner/5etools-docker
container_name: 5etools
volumes:
- ~/5etools-docker/htdocs:/usr/local/apache2/htdocs
ports:
- 8080:80
```
4. Bring up the stack with `docker-compose -f ~/5etools-docker/docker-compose.yml up -d` and wait for the container to finish starting. You can monitor its progress with `docker logs -f 5etools`.
5. Once the stack is online, you will need to download the json files for the homebrew you would like to auto-load and place them into the `~/5etools-docker/htdocs/homebrew/` folder, then add each filename to the `toImport:` array within `homebrew/index.json`.
This version has a persistent Docker-managed volume. If you would like to auto-load homebrew, you will need to switch to a host directory mapping, following the instructions in the Compose file.
# Auto-loading homebrew
To use auto-loading homebrew, you will need to use a host directory mapping as described above.
1. Start the container (using either `docker run` or `docker-compose`) and wait for the container to finish starting. You can monitor its progress with `docker logs -f 5etools-docker`.
2. Assuming you are using the mapping `~/5etools-docker/htdocs:/usr/local/apache2/htdocs` place your homebrew json files into the `~/5etools-docker/htdocs/homebrew/` folder, then add their filenames to the `~/5etools-docker/htdocs/homebrew/index.json` file.
For example, if your homebrew folder contains:
```
index.json
@ -108,4 +86,5 @@ Then your `index.json` should look like:
]
}
```
Note the commas after each entry except the last in each array.
Note the commas after each entry except the last in each array.
See the [wiki page](https://wiki.5e.tools/index.php/5eTools_Install_Guide) for more information.