Skip to content

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:

toml
[[mount]]
path = "/scpper/"
upstream = "http://127.0.0.1:8100"
strip_prefix = true
secret_file = "mount-scpper.key"
FieldDescription
pathPath to forward. Starts and ends with /, and cannot be under /-/ or /pw-api/
upstreamThe program's address
strip_prefixWhen true, path is removed before forwarding
secret_fileName 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, site and exp, plus "superuser": true when 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:

text
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 owns pgdata/ and from root. Run the program as that account, and connect with the database role recorded in pgdata/pwikit.role:

    text
    postgres://<role>@/pwikit?host=/opt/pwikit/pgdata&port=<port>
  • Windows. The bundled PostgreSQL listens on 127.0.0.1. The user name is pwikit and the password is in secrets/postgres-password:

    text
    postgres://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.

  1. Look up the values the later steps use:

    sh
    stat -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 slug
  2. Add the [[mount]] from Configuration to pwikit.toml, then restart pwikit:

    sh
    sudo /opt/pwikit/pwikit service restart

    The restart creates /opt/pwikit/secrets/mount-scpper.key.

  3. Install the PostgreSQL client and create a database for scpper:

    sh
    sudo 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 with Peer authentication failed.

  4. Download scpper and make it executable:

    sh
    sudo 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/scpper

    Create .env in the same folder:

    sh
    DATABASE_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.

  5. 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.target
    sh
    sudo systemctl daemon-reload
    sudo systemctl enable --now scpper
    journalctl -u scpper -f

    scpper serve and sync pwikit in the log mean scpper has started and reached pwikit's database. If the log shows Permission denied, check the permission set in step 4, then run sudo systemctl reset-failed scpper and sudo systemctl restart scpper.

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

sh
sudo -u <account> pg_dump "host=/opt/pwikit/pgdata port=<port> dbname=scpper user=<role>" > scpper.sql