5eTools is designed to be easily hosted by an individual, the is no central database or server, you can just put it on a thumb drive and open it up wherever you like.
However, running the website code is not as simple as just double-clicking the files, in the sections below, we’ll go over the different activities you may need to follow.
There are five things you may want to do with the code:
The site is developed and shared using node and github, using those tools for the steps above will give the best, if not simplest experience.
Use ofNode.jsandgitis recommended.
If you’re an advanced user wanting to make use of docker, then skip to the dedicated section below.
Your choice of method here is important, as it will affect what options are available to you in STEP 4: Updating the Site
This method is recommended and offers the simplest way to update while downloading the least duplicate content.
git.cmd into the address bar at the top of the folder window. Note: neither this folder nor any enclosing folder may contain contain a # or & character in its name.git clone https://github.com/5etools-mirror-3/5etools-src.git
https://github.com/5etools-mirror-3/5etools-2014-src.gitgit clone https://github.com/5etools-mirror-3/5etools-img.git 5etools-src/img
This method is not recommended for users who want to update the site content in future without re-downloading the entire site (~7Gb).
5etools-v#.###.#.zip
img-v#.###.#.z## files to sucessfully extract the images.# or & character in its name.
img-v#.###.#.zip file. You may need to use a more powerful tool than Windows Explorer for this (e.g. 7zip).img folder into the 5etools folder extracted above. It should be at the same level as other folders like data and js.This is an optional step where you can add some extra features to the site such as:
Use of these features is optional, you may not be interested in having lots of extra pages so you show up in Google.
Similarly you may not need to enable more extensive caching if all the files are already on your device for offline use.
This method is the only way to run the pre-written tools to enable these features.
npm i to complete first time setup of the site’s dependencies.The service worker—which adds a client-side network caching layer, improving performance and allowing offline use—is not committed to the repository, and so must be built locally.
npm run build:sw:prod to build the production service worker.This step generates ~7000 additional pages that each host a single piece of content, they are designed specifically to make the site more likely to show up in search engines like Google or Bing.
If you do not want to show up in search engines you should skip this step.
npm run build:seo to generate the Search Engine Optimisation pages.This step is how you host the website off your own machine, simply opneing them is not enough,they need to be “served”.
There are multiple mays to do this, but the recommended one is to use Node.js which the site is already setup for.
This method is recommended as other optional features require it.
npm run serve:dev in the terminal in the 5eTools folder.This method is not recommended as it needs an additional tool that is not part of the site
devd.exe file to the 5etools folder you extracted before. the one that contains the js folder.Tip for Windows
You can quickly open the terminal in a specific folder if you Shift-Right Click it and choose “Open Powershell/command line window here”
.\devd.exe . and press Enter. Do not forget the period at the end!You should be able to access the site, as long as you keep the command window open. Whenever you want to stop it, just close the window.
If you don’t want to mess with the console every time you start the site, you can create a batch file to do it for you.
devd.exe file to:"C:/path/to/5eTools/devd.exe" "/path/to/5eTools"
.batThis method is not recommended as it needs an additional tool that is not part of the site
python -m http.server
python -m SimpleHTTPServer if using Python 2.x.You may wish to specify a port at the end of the command
py -m http.server 8080.
If you specify a port other than the default 80, you will need to include that in your localhost URL, e. g. http://localhost:8080.
If you’re an advanced user wanting to make use of docker, then skip to the dedicated section below.
This step is dependent on how you downloaded the site originally in Step 1: Downloading the Site
If you did not originally clone it up with git then you will have to redownload the entire site manually.
This method is recommended as the only way to download only the differences between the last version of the site and the new version of the site.
git pull
cd img; git pull; cd ..npm run build:sw:prod or your site will seem to be stuck on the last version.npm i every once in a while to make sure the site depenedcies are up to date.This method is not recommended as you have to re-download the entire site (~7Gb).
This is a great time to start fresh withgitso you never have to do this again! See Step 1: Downloading the site for more information.
npm run build:sw:prod. Your site will appear to be stuck on the last version unless you do.npm i on occasion to update any dependencies the site needs.This is mostly outside the scope of this guide but here’s some things to know:
package.json file has a list of npm tasks that do helpful things.README.md file is full of useful notes on conventions and tasks etc.node\build-sw.mjs) so files stored in a draft subfolder do not become locked in cache.- "homebrew/**/*.json", // presumably if there is homebrew data it should also be loaded
+ "homebrew/*.json", // root level homebrew
+ "homebrew/**/!(draft)/*.json", // all homebrew except brew in folder called "draft"
This section is for advanced users intending to use the docker environment.
You can find the docker image and its links in the code’s repository, under Packages.
Place the provided contents in a docker-compose.yml file inside a directory of some sort dedicated to this task and run all commands from inside that directory.
version: "3"
services:
5etools:
image: <docker image url here> # set this to the current latest version.
restart: unless-stopped
ports:
- "8080:80" # where 8080 is the port on the machine and 80 is the internal port of the container. ie change 8080 to change which port you want to access the webserver at.
The following is a basic tutorial to use docker-compose.
# start the stack
docker-compose up -d
# stop the stack
docker-compose stop
# delete the stack
docker-compose down
# view logs for the stack
docker-compose logs
# run the container
docker run -p 8080:80 --restart unless-stopped --name someuniquename <docker image url here>
# stop the container
docker container stop someuniquename
# delete the container
docker container rm someuniquename
# logs for the container
docker container logs someuniquename
If you want to modify the files contained in the image in some way, clone the repo, change the files however you want, and build the container.
# clone the repo
git clone <repo url here>
# build the image
docker build -t imagename:version .
# run the image using the command in the Docker section changing ghcr.io/5etools-mirror-3/5etools:latest to imagename:version
Port
80is the containers internal port.
The
.dockerignorefile ignores all new files by default, unless they match explictly allowed patterns. If you add a new file make sure it will be found by the existing patterns in the.dockerignorefile. To add a new pattern/file in the container add this line!pattern/file.