Pepperminty-Wiki/docs/04-Getting-Started.md

Getting Started

System Requirements

• PHP-enabled web-server (must be at least PHP 7+; only versions of PHP that are officially supported are supported by Pepperminty Wiki)
• PHP session support (for logging in, see here for more information)
  • Alpine Linux users: install e.g. php84-session
• The following PHP extensions:
  • mbstring (for utf8 string handling - currently required)
  • imagick (for preview generation)
  • fileinfo (for proper mime type checking of uploaded files)
  • zip (for compressing exports)
  • intl (for Unicode text normalization when searching and in the id index, and when sending emails when utf-8 mode is disabled)
  • pdo_sqlite3 (for search index storage; uses PDO) **
• Write access to Pepperminty Wiki's own folder (only for editing and first run)
• Recommended: Block access to peppermint.json, where it stores it's settings (including passwords!)

** Note for Alpine Linux users: That means pdo_sqlite! i.e. from php84-pdo_sqlite from Alpine's testing repository, ref php -m inside an alpine Docker container and this post

Setup Instructions

1. Once you've ensured your web server meets the requirements, obtain a copy of Pepperminty Wiki (see Getting a copy).
2. Put the index.php file on your web server.
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 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!)

Blocking access to pepppermint.json

Nginx

For those running Nginx, this configuration snippet should block access to peppermint.json:

location /peppermint.json {
	deny all;
}

Apache

If you are running Apache, then the following configuration snippet should block access to peppermint.json (credit: @viradpt):

<Files "peppermint.json">
    Order Allow,Deny
    Deny from all
</Files>

Lighttpd

If you're running lighttpd, then you need to load the mod_access module:

server.modules += ( "mod_access" )

If you already have a server.modules directive, simply add mod_access to the list if you haven't already. Then, just block access like so:

$HTTP["url"] =~ "^/peppermint.json" {
     url.access-deny = ("")
}

Caddy

The Caddy web server makes it easy to block files. Add this to your server block if you have one, or if not just to the end of your Caddyfile:

@blocked {
    path *peppermint.json
}
respond @blocked 403

Microsoft IIS

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.

SETLOCAL
SET installdir=c:\inetpub\wwwroot\pepperminty\
SET iissitename="Default Web Site"
SET iisappfull="Default Web Site/pepperminty"
SET iisapppath="/pepperminty"

cd /d %WINDIR%\system32\inetsrv\
appcmd add app /site.name:%iissitename% /path:%iisapppath% /physicalPath:%installdir%
appcmd set config %iisappfull% -section:system.webServer/security/requestFiltering /+"hiddenSegments.[segment='peppermint.json']"
cd /d %installdir%
icacls . /grant IIS_IUSRS:(OI)(CI)RXWM
ENDLOCAL

Other web servers

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 to get in touch - and then we can add your configuration snippet to improve this documentation for everyone.

Verifying Your Download

Advanced and privacy-conscious users may want to verify the authenticity of their downloaded release. Since v0.21.1-hotfix1, Pepperminty Wiki releases on GitHub 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 cded 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:

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:

gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys C2F7843F9ADF9FEE264ACB9CC1C6C0BB001E1725

Then, verify the GPG signature:

gpg --verify HASHES.SHA256.asc

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:

echo -e "4\nsave\n" | gpg --batch --expert --command-fd 0 --edit-key "C2F7843F9ADF9FEE264ACB9CC1C6C0BB001E1725" trust >/dev/null 2>&1;

Then, simply re-run the GPG verification command above to see the difference.

Docker

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 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 cding to a nice directory and cloning the Pepperminty Wiki git repository:

git clone https://github.com/sbrl/Pepperminty-Wiki.git
cd Pepperminty-Wiki;

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:

./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 in peppermint.json - which it is also recommended to change if 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.

mkdir path/to/directory
sudo chown 10801:10801 path/to/directory

Then, create peppermint.json and prefill it with the following contents:

{ "data_storage_dir": "/srv/data", "firstrun_complete": false }

....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:

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 (and 9800c25 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:

docker run -it --rm -v /absolute/path/to/peppermint.json:/srv/app/peppermint.json --hostname peppermint -v /absolute/path/to/data:/srv/data pepperminty-wiki

...replacing:

• /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 to docker run.

docker-compose

If you use Docker Compose, the following Docker Compose file may prove useful:

services:
  pepperminty-wiki:
    image: pepperminty-wiki
    container_name: peppermint
    volumes:
      - /absolute/path/to/peppermint.json:/srv/app/peppermint.json
      - /absolute/path/to/data:/srv/data

...replacing the source paths in volumes as previously described.

Note that this Docker Compose file is untested. If this doesn't work for you, please open a pull request.

Alternate docker-compose file

This file HAS been tested (on a raspberry pi), but uses named volumes, which are not strictly neccesary.

These settings are:

• 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.

version: "3"

services:
  tribblewiki:
    image: pepperminty-wiki
    container_name: wiki
    restart: unless-stopped
    volumes: 
      - wiki-app:/srv/app
      - wiki-data:/srv/data

volumes:
  wiki-app:
    name: "WikiAppFolder"
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: './app'
  wiki-data:
    name: "WikiDataFolder"
    driver: local
    driver_opts:
      type: 'none'
      o: 'bind'
      device: './data'

How to use the alternate docker-compose file.

This guide is for Linux. Windows machines will need different commands etc.

1. Build the container (see above) on the machine you want to run the container on.
   • 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.

   •                |- 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.

Completing the first run wizrd

Now that your Docker container is started, you should be able to navigate to it in your web browser to complete the first run wizard.

Setups vary, but if you don't know the IP address of your shiny new Docker container, try this method:

First get the container ID:

docker ps

(First column is for container ID)

Use the container ID to run:

docker inspect <container ID>

At the bottom, under NetworkSettings, you can find [the] IPAddress [field]

Or just do for UNIX based [operating systems]:

docker inspect <container id> | grep "IPAddress"

(Taken from This StackOverflow Answer)

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.
• Fill in all other fields as your needs require.

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.