- PHP-enabled web-server (must be at least PHP 7+; only versions of PHP that are [officially supported](https://www.php.net/supported-versions.php) are supported by Pepperminty Wiki)
**\*\* Note for Alpine Linux users:** That means `pdo_sqlite`! i.e. from [`php84-pdo_sqlite`](http://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/php84-pdo_sqlite-8.4.0_beta3-r0.apk) from Alpine's testing repository, ref `php -m` inside an alpine Docker container and [this post](https://devcoops.com/install-php-mbstring-on-alpine-linux/)
3. Navigate to Pepperminty Wiki in your web browser. If you uploaded the `index.php` to `wiki/` on your web server `bobsrockets.com`, then you should navigate to `bobsrockets.com/wiki/`.
4. See the [Configuring](06-Configuration.html) section for information on how to customise your installation, including the default login credentials.
5. Ensure you configure your web server to block access to `peppermint.json`, as this contains all your account details (including your hashed password!)
If you are running Apache, then the following configuration snippet should block access to `peppermint.json` (credit: [@viradpt](https://github.com/sbrl/Pepperminty-Wiki/issues/224#issuecomment-912683114)):
For those running IIS, the following will grant the appropriate read and write permissions to the IIS_IUSRS group, and prevent the peppermint.json file from being retrieved.
Open an elevated (administrator) Command Prompt and run the following.
Change the "installdir" variable to the directory where you've placed the Pepperminty index.php file.
This assumes your IIS website is named "Default Web Site" and that you want to create a "pepperminty" application under it. If yours is different, change the variables appropriately.
If you aren't running any of these web servers and have a configuration snippet to share for your web server, please [open an issue](https://github.com/sbrl/Pepperminty-Wiki/issues/new) to get in touch - and then we can add your configuration snippet to improve this documentation for everyone.
Advanced and privacy-conscious users may want to verify the authenticity of their downloaded release. Since [v0.21.1-hotfix1](https://github.com/sbrl/Pepperminty-Wiki/releases/tag/v0.21.1-hotfix1), [Pepperminty Wiki releases on GitHub](https://github.com/sbrl/Pepperminty-Wiki/releases) are now signed. This is done in the following fashion:
- The release `index.php` is hashed with SHA256 and saved to `HASHES.SHA256`
-`HASHES.SHA256` is then signed via GPG, generating `HASHES.SHA256.asc` as the signature file
Thus, verifying the authenticity of a downloaded release is a 2-step process. It is assumed in this section that the user is familiar with a Linux terminal, and has one opened in which they have `cd`ed to the directory containing the files downloaded from a release.
3 files should be present:
Filename | Purpose
--------------------|----------------------
`index.php` | Pepperminty Wiki itself
`HASHES.SHA256` | The SHA256 hash(es)
`HASHES.SHA256.asc` | The GPG signatue
First, the SHA256 hashes must be verified:
```bash
sha256sum -c HASHES.SHA256
```
This should output something like `OK` if verification successful, or an error message if not.
Next, the GPG signature can be verified. To do this, we need to download the public key with which the release was signed. At the current time, this is my personal GPG key with the id `C2F7843F9ADF9FEE264ACB9CC1C6C0BB001E1725`, but check the release notes too. Download it like so:
It might complain that the key is untrusted, but it should also tell you which key signed the release, and whether the signature itself is valid or not - which is what you're looking for. If you'd like to mark the key you downloaded as trusted, you can do so like this:
The recommended way of running Pepperminty Wiki is with a plain PHP-enabled web server. However, a Dockerfile is available in Pepperminty Wiki's git repository.
**Warning:** Installing Pepperminty Wiki with Docker is somewhat complicated, involving multiple steps. If this seems scary to you, it is recomended you use a plain PHP-enabled web server as described above.
**If you do not want to use Docker, you can skip the rest of this page and move onto the next one.**
This said, there are 4 steps to getting Pepperminty Wiki running in a Docker container:
1. Building the Docker container
2. Creating the file structure
3. Starting the Docker container
4. Completing the first run wizard
This guide will assume a plain Docker container running on a generic Linux box that has Docker installed. Of course, you can adapt this to container orchestration setups (e.g. Kubernetes, Docker Swarm, etc ~~[Nomad](https://www.infoq.com/news/2023/08/hashicorp-adopts-bsl/)~~ nope, the BSL license is bad).
If you do adapt it, please do open a pull request to update this guide with your instructions!
### Building the Docker container
Start by `cd`ing to a nice directory and cloning the Pepperminty Wiki git repository:
Now, check out the git tag you want to build, if any. Stay as-is to build the latest development version.
Next, we simply use the `build.sh` script like so:
```bash
./build.sh docker
```
....this will build Pepperminty Wiki in the background, so it requires a working PHP install (no FPM required, only uses the CLI) with the `zip` PHP extension available.
Once done, it will create a new Docker image with the tag `pepperminty-wiki`.
You are now free to delete the cloned git repository, but it is advised to update regularly. If you are planning to script the update of the Docker container, the format of the giit tags can be relied upon.
- The latest git tag will be either the latest release or the latest beta/pre release
- Release tags look like this (replacing the version/hotfix numbers of course):
-`v0.20`
-`v0.20.2-hotfix2`
-`v0.20.3`
- Beta release tags look like this:
-`v0.19-beta2`
### Creating the file structure
Traditionally, Pepperminty Wiki keeps everything in a single directory, but in a Docker container is most likely desirable to keep the wiki data in a separate directory. Pepperminty Wiki supports this mode of operation through the [`data_storage_dir` configuration directive](https://starbeamrainbowlabs.com/labs/peppermint/peppermint-config-info.php#config_data_storage_dir) in `peppermint.json` - which it is also recommended to change if [`require_login_view`](https://starbeamrainbowlabs.com/labs/peppermint/peppermint-config-info.php#config_require_login_view) is set to true to avoid leaks.
To this end, there are 2 things we need to do here.
First, create an empty directory for Pepperminty Wiki to store your wiki data in, and `chown` it to `10801:10801` (UID:GID), since Pepperminty Wiki will bbe running under this user/group id combination inside the Docker container to improve security.
```bash
mkdir path/to/directory
sudo chown 10801:10801 path/to/directory
```
Then, create `peppermint.json` and prefill it with the following contents:
....the `data_storage_dir` here is INSIDE the container, not outside! The `"firstrun_complete": false` is required to show the firstrun installer.
Then, set the permissions on `peppermint.json`:
```bash
chmod 0600 path/to/peppermint.json
sudo chown 10801:10801 path/to/peppermint.json
```
**Note:** This method only works for Pepperminty Wiki v0.25 or above. Specifically, you MUST have commit [`c4f6ef2`](https://github.com/sbrl/Pepperminty-Wiki/commit/c4f6ef2c58afb291f3fb6e355eb0eeff00843cc5) (and [`9800c25`](https://github.com/sbrl/Pepperminty-Wiki/commit/9800c257de64774cc8e09e2a75f4de6a1dcb6ac2) immediately before it) for the firstrun wizard to correctly appear without editing `peppermint.json` a second time.
### Starting the Docker container
Now that you have the Docker image built and the file structure setup correctly, you can start the Docker container itself. This is the Docker command required as if you were starting it in the terminal:
-`/absolute/path/to/peppermint.json` with the path to `peppermint.json`, and
-`/absolute/path/to/data` with the path to the wiki data directory you created earlier.
...make sure that both of these paths are **absolute**, because otherwise you will experience issues because the Docker daemon that actually starts the Docker container does not know about your current working directory.
It is also strongly advisable to avoid spaces in your directory paths.
**Tip:** A simple solution to ensure the Docker container automatically restarts on reboot is to use [the `--restart always` argument](https://docs.docker.com/engine/containers/start-containers-automatically/#use-a-process-manager) to `docker run`.
#### docker-compose
If you use Docker Compose, the following Docker Compose file may prove useful:
- Named volumes (They may or may not need the driver and driver-opts sections, has not been tested without them. They definitely work with them in.)
- **NB:** You must add the named volume folders to the same directory as your docker-compose file _before you run it_. Weird stuff happens if you don't.
- Relative filepaths work fine with docker-compose, as long as they're relative to the location of the docker-compose file.
- However, absolute filepaths are always the safest option.
- Building it on the machine itself means you don't need to worry about the motherboard/kernel type - it will build the correct one for that machine automatically.
- If you need to install Apache in order to install PHP so you can build it, remember to turn the 'start on boot' setting off. (Also just turn it off straight away, you don't need it to build.)
`sudo systemctl disable apache2`
2. Set up the directory you want your docker-compose to live in.
- You need your docker-compose file, plus the directories that the named volumes will be living in, all in the same folder.
- ``` -Directory-|- app
|- data
|- docker-compose.yaml```
3. OPTIONAL - If you want to be able to edit your peppermint.json file without using sudo (eg. using some kind of GUI):
- Create a new group (eg. pepperminty) with the gid 10801 (or, if you've changed it, to whatever gid is used by pepperminty wiki)
`sudo groupadd pepperminty -g GID`
- Add your editing user (eg. wikiadmin) to the pepperminty group
`sudo usermod -a -G pepperminty wikiadmin`
- Assuming the install went as planned, this should allow you to edit peppermint.json.
- However, if you're still getting access denied problems...
- Reboot your computer. Usergroup stuff likes a reboot.
- Make sure that peppermint.json has 'User and Group' write access. If for some reason it doesn't, you'll need to set it.
`chmod 664 /path/to/peppermint.json`
- Remember to reboot after you do this, too! Just in case.
- Double check the user you're using is in the pepperminty group.
- If you want to edit other files, you can also use this method! However, you'll have to change the write access permissions first; all files other than peppermint.json are likely to be created with 'Only User' write permissions.
`chmod 664 /path/to/file_to_edit.md`
4. Start the container
`docker-compose up -d`
5. First run wiki time! (See below)
#### Troubleshooting
__I can't connect to the wiki!__
Did you make sure to turn Apache off? If you've recently rebooted and suddenly have this problem, make sure it's not set to start on boot.
Otherwise, it's likely a networking issue (are you using a reverse proxy, like Traefik? It's pretty easy to typo in the labels section of a docker-compose...)
__I get a white screen when I try and save a page__
You probably have some kind of permissions mismatch somewhere. :(
Suggestion: back up everything before you try and fix it, it may be easiest to nuke the entire container and start again.
__I can't edit peppermint.json__
Take a look at Step 3 above, it's probably a permissions issue. If all else fails, you can edit it with sudo on a terminal.
_(Taken from [This StackOverflow Answer](https://stackoverflow.com/a/46310428/1460422))_
The Pepperminty Wiki Docker container always listens on port 80 for unencrypted HTTP requests, so enter something like the following IP address into your web browser:
```
http://172.17.0.3/
```
**Note:** The IP address will vary depending on your network layout. It is important you put it behind another reverse proxy that handles HTTPS encryption if you want it to be world-readable.
In your web browser, you should be presented with the first run wizard, which should tell you that all the PHP extensions needed are already installed.
Fill this out as normal:
- Pepperminty Wiki will add a `secret` field to Pepperminty Wiki - follow the on-screen instructions
- Put `/srv/data` into the "Data Storage Directory" field.
Finally, press the "Create Wiki!" button to finish the first run wizard, and now use your wiki as normal.
### FAQ
#### I get a "peppermint.json.compromised" exists on disk error
The error message may look like this:
> Error: peppermint.json.compromised exists on disk, so it's likely you need to block access to 'peppermint.json' from the internet. If you've done this already, please delete peppermint.json.compromised and reload this page.
>
> If you've done this check manually, please set the disable_peppermint_access_check setting to false.
>
> This check was done as part of the first run wizard.
....try restarting the container. The container is designed to block access to `peppermint.json` automatically.
If you do encounter this bug, please do get in touch so we can track it down and fix it.
#### I get an "Error: Failed to decode the settings file! Does it contain a syntax error?" message
Check the permissions on your `peppermint.json`. It should be owned by UID 10801 and GID 10801. It should also be a file containing some JSON, and not a directory.
