Skip to content

Installation guide

Jump to bottom
Spappz edited this page Jul 22, 2024 · 2 revisions

Pf2eTools has no API and little to no back-end, meaning that the hardware and software requirements are especially light. This guide will walk you through the process of installing the site locally, which means that you can access it even if you're not connected to the internet.

By default, the installation will be private: it won't be accessible by other devices.

In a nutshell

git clone https://github.com/Pf2eToolsOrg/Pf2eTools
cd Pf2eTools
npm i
npm run build
npm run serve:dev

In detail

For standard computers and servers, the process is fairly similar, regardless of your OS.

You can also install the site on Android.

Downloading the site

You have two options to download the site. You can either use the command-line tool Git, or you can simply download everything from the Releases page.

The benefit of using Git is that you can handle updates much more smoothly, as well as preview unreleased test versions. The benefit of downloading a the release is that it's marginally more lightweight (we're talking about ~30 MB less), and you don't need to install Git.

git clone (recommended)

  1. Download and install Git.
    • If you're on macOS, you might have it already installed (try git version in Terminal).
    • On Debian and Ubuntu, you can install it via sudo apt-get install git-all.
  2. In the Command Prompt/Terminal, navigate to the directory into which you want to install the site.
    • On Windows, you can navigate to the directory of your choice in File Explorer. Once you're there, type cmd into the address bar at the top and press ENTER.
    • Otherwise, on all platforms, you can navigate using cd <path>: for example, cd C:\Users\...\myFolder on Windows or cd ~/.../myFolder on macOS and Linux.
    • Note: neither this directory nor any enclosing directory may contain contain a # or & character in its name.
  3. Type and run git clone https://github.com/Pf2eToolsOrg/Pf2eTools. This may take a while!
  4. Verify that a new directory called Pf2eTools exists.

Static release

Simply download the Pf2eTools-v###.zip archive from the Releases page and extract the compressed files into a directory of your choice. Note: neither this directory nor any enclosing directory may contain contain a # or & character in its name.

Building the site

  1. Install NodeJS along with its package manager, npm.
    • If you're familiar with command-line tools, you can instead use a Node version manager. Pf2eTools only updates its dependencies very rarely, so this is not strictly required.
  2. In the Command Prompt/Terminal, navigate to the directory you installed the site into, as above.
  3. Run npm i. This may take a while!
  4. Run npm run build. This may also take a while!

Running the site

Once you've installed Pf2eTools as above, this is the step you'll be repeating over and over again.

Bear in mind that this guide teaches you how to run the website in the foreground. This means that, if you close the Command Prompt/Terminal window running the website, your website will stop responding. Running the website in the background is beyond the scope of this guide, but we've got some pointers!

NodeJS (recommended)

  1. In the Command Prompt/Terminal, navigate to the directory you installed the site into, as above.
  2. Run npm run serve:dev.
  3. Open localhost:8080 in your browser.

Python

  1. Install Python. Note: Python is preinstalled on macOS and Ubuntu.
  2. In the Command Prompt/Terminal, navigate to the directory you installed the site into, as above.
  3. Run python -m http.server.
  4. Open http://localhost/ in your browser.

devd

  1. Download devd, extract it, and move it to the Pf2eTools folder.
  2. Open the terminal (Command Prompt) and navigate to the Pf2eTools folder. The command to do so is cd (ex. cd C:\Users\userName\Downloads).
  3. Type and run ".\devd.exe" . (Windows) or ./devd . (macOS and Linux).
    • You can add the -o flag to automatically open the site in browser, or the -l flag to live-reload.
    • See devd's README for more information.
  4. Open localhost in a browser.

Updating the site

If you cloned the repository via Git, simply run git pull from within that directory followed by npm i and then npm run build. Note: this will pull the latest, potentially unreleased version of the site, if changes have already been made since the last release. Although bugs are rare, they may occur! Let us know if you find anything unexpected.

If you downloaded the .zip release file from the Releases page, delete it. Re-download the new package as if starting from scratch, although you can typically skip reinstalling Node.js.

Extensions

Once you've got the site running, you might be interested in customising things further. Here's some ideas—they're all outside the scope of this guide, but you're welcome to explore them. If you have any questions, we're always available on Discord!

  • Automatically run your site in the background on start-up (pm2)
  • Expose your site to your local network (port forwarding)
  • Expose your site to the internet (OpenSSL, the npm run build:data:prod and npm run build:deploy:prod scripts)
  • Make homebrew edits to statblocks (data/ directory)
  • Contributing to the Pf2eTools project with data conversion, bug fixes, or new features (Git, the #pf2etools-general channel in our Discord server)

Android installation

  1. Download and extract the Pf2eTools-v###.zip archive from the Releases page. Note: neither this directory nor any enclosing directory may contain contain a # or & character in its name.
  2. Install a web-server application, such as Tiny Web Server.
  3. In the web-server application, change the server's directory to your extracted Pf2eTools directory.
  4. Turn on the server and open localhost:8080 in a browser. If you changed the port number, modify the 8080 with your chosen port.

Other pages will be added as the site and wiki expands.

Clone this wiki locally