Mounting other programs
pwikit can forward a path on the site to another program on the same machine, such as /scpper/ to scpper. Readers still visit one site, and pwikit tells the program who is signed in.
Configuration
Add one [[mount]] per program to pwikit.toml, then restart pwikit:
[[mount]]
path = "/scpper/"
upstream = "http://127.0.0.1:8100"
strip_prefix = true
secret_file = "mount-scpper.key"| Field | Description |
|---|---|
path | Path to forward. Starts and ends with /, and cannot be under /-/ or /pw-api/ |
upstream | The program's address |
strip_prefix | When true, path is removed before forwarding |
secret_file | Name of the key file in secrets/ in the data directory. If it does not exist, pwikit creates it at startup |
A mount applies to every site on the instance. Give the contents of the key file to the program.
Reader identity
When the reader is signed in, forwarded requests carry an X-Pwikit-User header holding <body>.<signature>:
- The body is a JSON object in unpadded base64url, holding
id,username,name,siteandexp, plus"superuser": truewhen the reader is a superuser. - The signature is the HMAC-SHA256 of the body under the key, in hexadecimal.
exp is a Unix time one minute after signing. Check the signature and exp before trusting the identity.
Sending notifications
A program can send readers notifications, which appear on their Notifications page:
POST /pw-api/mounts/notify
X-Pwikit-Mount: /scpper/
X-Pwikit-Signature: <HMAC-SHA256 of the request body, in hexadecimal>
Content-Type: application/json
{"users": [12, 34], "title": "You were tipped", "message": "...", "link": "/scp-001"}Send it to the site's own address, signed with the same key. users holds at most 500 user IDs; title is at most 100 characters; message is at most 2,000 characters and shown as plain text; link is optional and has to be a path on the site. It returns 204 on success.
Reading site data
A program that needs pages, ratings and similar data can read pwikit's database directly.
With your own PostgreSQL, create a read-only account on pwikit's database for the program.
With the bundled PostgreSQL, how to connect depends on the system. The port is recorded in pgdata/pwikit.conf in the data directory.
Linux and macOS. The bundled PostgreSQL accepts connections only through the socket in
pgdata/, and only from the account that ownspgdata/and from root. Run the program as that account, and connect with the database role recorded inpgdata/pwikit.role:textpostgres://<role>@/pwikit?host=/opt/pwikit/pgdata&port=<port>Windows. The bundled PostgreSQL listens on
127.0.0.1. The user name ispwikitand the password is insecrets/postgres-password:textpostgres://pwikit:<password>@127.0.0.1:<port>/pwikit
These accounts have full access to the database. Give them only to programs you trust.
Example: deploying scpper
scpper adds coins, card draws and branch indices to a site. These steps assume pwikit is installed in /opt/pwikit on Linux with the bundled PostgreSQL, and scpper goes in /opt/scpper.
Look up the values the later steps use:
shstat -c %U /opt/pwikit/pgdata # account to run scpper as sudo cat /opt/pwikit/pgdata/pwikit.role # database role sudo grep port /opt/pwikit/pgdata/pwikit.conf sudo -u <account> /opt/pwikit/pwikit site list # site slugAdd the
[[mount]]from Configuration topwikit.toml, then restart pwikit:shsudo /opt/pwikit/pwikit service restartThe restart creates
/opt/pwikit/secrets/mount-scpper.key.Install the PostgreSQL client and create a database for scpper:
shsudo apt install postgresql-client sudo -u <account> psql "host=/opt/pwikit/pgdata port=<port> dbname=pwikit user=<role>" -c "CREATE DATABASE scpper"The
user=<role>part is required. Without it the connection fails withPeer authentication failed.Download scpper and make it executable:
shsudo mkdir -p /opt/scpper sudo wget -O /opt/scpper/scpper https://github.com/scpwikicloud/scpper/releases/latest/download/scpper_linux_amd64 sudo chmod +x /opt/scpper/scpperCreate
.envin the same folder:shDATABASE_URL=postgres://<role>@/scpper?host=/opt/pwikit/pgdata&port=<port> PWIKIT_DATABASE_URL=postgres://<role>@/pwikit?host=/opt/pwikit/pgdata&port=<port> PWIKIT_SITE=<site slug> PWIKIT_SECRET_FILE=/opt/pwikit/secrets/mount-scpper.key HTTP_ADDR=127.0.0.1:8100 PWIKIT_URL=https://<site domain>Then run
sudo chown -R <account>:<account> /opt/scpper.Create
/etc/systemd/system/scpper.service:ini[Unit] Description=scpper After=network.target [Service] User=<account> WorkingDirectory=/opt/scpper ExecStart=/opt/scpper/scpper serve Restart=on-failure [Install] WantedBy=multi-user.targetshsudo systemctl daemon-reload sudo systemctl enable --now scpper journalctl -u scpper -fscpper serveandsync pwikitin the log mean scpper has started and reached pwikit's database. If the log showsPermission denied, check the permission set in step 4, then runsudo systemctl reset-failed scpperandsudo systemctl restart scpper.Open
https://<site domain>/scpper/. Superusers become scpper administrators when they visit.
To show coins on profiles and use the wealth ranking and tip button on pages, also install the scpper plugin. See Plugins.
To update scpper, run sudo -u <account> /opt/scpper/scpper update, then sudo systemctl restart scpper.
pwikit backup create does not include scpper's database. Back it up separately:
sudo -u <account> pg_dump "host=/opt/pwikit/pgdata port=<port> dbname=scpper user=<role>" > scpper.sql