Operations

Day-to-day running of a ProjectWikit instance: the system service, logs, backups, upgrades and recovering access. Installing pwikit and registering the service for the first time are covered in Deployment. Every command used here is described in Command line.

Examples assume pwikit is installed in /opt/pwikit on Linux and macOS and in C:\pwikit on Windows, with the data directory next to the executable.

Managing the system service

pwikit service install registers pwikit serve with the operating system under the name pwikit. If you installed it with -name, pass the same -name to every command below.

pwikit service start
pwikit service stop
pwikit service status
pwikit service uninstall

Run them with sudo on Linux and macOS, and from a terminal opened with Run as administrator on Windows. On Linux and Windows, status works from any account.

• Linux. The service is the systemd unit /etc/systemd/system/pwikit.service, so systemctl works on it as well.
• macOS. A service installed with sudo is /Library/LaunchDaemons/pwikit.plist and starts at boot. One installed without sudo is ~/Library/LaunchAgents/pwikit.plist, starts when you log in, and is managed without sudo. A service installed one way is not visible the other way.
• Windows. The service appears as ProjectWikit in the Services console and runs under the virtual account NT SERVICE\pwikit.

Stopping gives pwikit up to three minutes to shut down cleanly, including its PostgreSQL. Stopping the service does not stop it from starting at the next boot; uninstall does. uninstall also removes the firewall rules and closes the ports that install opened.

When pwikit stops unexpectedly

When pwikit exits with an error, the service manager starts it again. If the bundled PostgreSQL stops while pwikit is running, pwikit stops as well and logs the reason, and the restart starts both again. After an unclean stop, PostgreSQL first replays its journal, which can take a while.

Running commands next to the service

Commands such as pwikit backup create or pwikit site list can run while the service is running; with the bundled PostgreSQL they use the PostgreSQL the service started. On Linux and macOS, run them from the account the service runs as, not as root:

sudo -u wiki /opt/pwikit/pwikit backup create

Logs

pwikit's log

How pwikit runs	Where the log goes
In a terminal	Standard error, or the file given with -log-file
Linux service	The systemd journal: journalctl -u pwikit -f
macOS service	logs/pwikit.log, plus logs/pwikit-stderr.log for crashes and for anything written before the log file opens
Windows service	logs/pwikit.log. When the service stops because of an error, the error is also written to the Windows Event Log (Application log, source pwikit)

Log files are rotated at 10 MB, keeping 5 old files.

PostgreSQL logs

When pwikit runs the bundled PostgreSQL, PostgreSQL writes its logs to logs/ in the data directory and keeps only the last week. When PostgreSQL fails to start, the reason is in logs/postgresql-start.log.

With your own PostgreSQL, its logs are wherever that server keeps them.

Backups

What a backup contains

pwikit backup create writes one .pwbak file. It holds:

• every table of the database: all sites, accounts, pages and their history, forum, settings;
• the uploaded files in files/, unless -no-files is given;
• a manifest recording when and by which pwikit the backup was made, the PostgreSQL version, the schema migrations the database had, and the row count and checksum of every table and file.

A backup does not contain pwikit.toml, secrets/, logs/ or the executable. Keep copies of pwikit.toml and secrets/ separately; see The secrets directory.

A backup is a logical copy, not a copy of pgdata/. It can be restored on another machine, into the bundled PostgreSQL or your own, and into a different PostgreSQL version (14 or newer).

Creating a backup

pwikit backup create

The file goes to backups/pwikit-<UTC time>.pwbak; use -output for another path. The backup can be made while pwikit is serving: all tables are read as one consistent snapshot, and the files are read after the tables. While it runs, the table data is staged in the system's temporary directory, so that directory needs free space roughly the size of the database. An interrupted run leaves no file under the final name.

Checking and listing backups

pwikit backup list
pwikit backup verify backups/pwikit-20260911-030000.pwbak

list shows the backups in backups/. verify reads the whole file and reports damaged or missing contents, and a backup made by a newer pwikit. Neither command needs the database.

Restoring a backup

A restore replaces the whole database, and the uploaded files if the backup holds them and -no-files is not given.

1. Stop pwikit:

   sudo ./pwikit service stop

2. Restore:

   pwikit backup restore backups/pwikit-20260911-030000.pwbak -force

3. Start pwikit again.

pwikit must be stopped. If pwikit serve or anything else is connected to the database, the restore stops with an error and changes nothing. Stop the service or the program holding the connection, and run the command again.

-force. A database that already holds data, such as sites, accounts or pages, is only replaced with -force. Without it the command stops and changes nothing. A database that holds only what pwikit writes when it first starts counts as empty, so a new instance that has been started once, but has no site yet, needs no -force.

The safety backup. Before changing anything, restore backs up the current database and files to backups/before-restore-pwikit-<UTC time>.pwbak and prints its path. If that backup fails, nothing is changed. To go back on a restore, restore this file. -no-safety-backup skips it. With -no-files, the safety backup leaves the files out, because they are not changed. When the database holds no data yet, this step is skipped.

What happens.

1. The backup is verified in full. A damaged backup is refused and nothing is changed.
2. The database is emptied and refilled from the backup in a single transaction. If any step fails, the database is left as it was.
3. If the backup was made by an older pwikit, the schema migrations added since are applied.
4. If the backup holds uploaded files, they are written next to files/ and then swapped in. The previous directory is kept as files.replaced; an older files.replaced is deleted first. Delete files.replaced yourself once you are satisfied. A backup without files, or a restore with -no-files, leaves files/ alone.

A backup from a newer pwikit is refused, and nothing is changed. Restore it with that pwikit version or a later one.

Restoring into your own PostgreSQL. Create an empty database on a PostgreSQL 14 or newer that provides the citext and pg_trgm extensions, then:

pwikit backup restore backups/pwikit-20260911-030000.pwbak \
  -database "postgres://pwikit:secret@db.internal:5432/pwikit"

Uploaded files still go to files/ in the data directory. Then set database in pwikit.toml (or -database, or DATABASE_URL) so that pwikit serve uses that database; see Configuration.

When a restore fails or does not take

A failed restore prints the reason and exits with an error. Check, in order:

1. Read the last lines the command printed; they give the reason.
2. Run pwikit backup verify <backup file> to confirm the file is intact. A checksum mismatch usually means the copy or upload was incomplete; copy the file again.
3. Run pwikit service status to confirm the service is stopped, then run the restore again.

If the restore reported no error but pwikit site list still shows the sites from before:

• Look in backups/ for a before-restore-pwikit-<UTC time>.pwbak from this run. If it is there, the restore started but failed while writing the database, and the database was left as it was; check the steps above and try again. If it is not, the restore stopped before it began, for example because the service was still running. No such file is written with -no-safety-backup, or when the database held no data yet.
• Make sure the command and the service use the same data directory. A command uses the directory holding the pwikit executable, even when it is run through the pwikit on your PATH. If the service was installed with another -data-dir, pass the same -data-dir to the command. On Linux, the ExecStart line printed by systemctl cat pwikit shows the directory the service uses.

Exporting a single site

pwikit backup create -site main

-site writes a backup of one site, named pwikit-<slug>-<UTC time>.pwbak, for moving that site to a new instance. It is checked and restored like any other backup.

Included	Left behind
The site and its site settings	Other sites
Pages, their revisions, authors, tags, ratings and favourites, page history and search index	Private messages and blocks between users
Attachment records of its pages	Notifications
Categories and their permission settings, tags and tag categories, themes	The addresses accounts signed in from, used by Suspicious activity
Roles and role categories, their permissions and members	Sessions: everyone signs in again
Forum sections, categories, threads, posts, post revisions and likes	Accounts that appear nowhere in the site
Invite links, user reports, support tickets, the admin log
Watches on its pages and threads
Backlinks from its pages; a link to another site of the instance no longer records which site
Every account that appears in any of the above, with its preferences

Uploaded files. The files/ directory is shared by all sites of an instance, and -site includes it whole, including the files of other sites. Add -no-files when other sites' files must not leave the instance; the export then has no attachments.

Accounts.

• Superuser rights are removed from every exported account, and the API keys of bot accounts are cleared. The operator of the new instance makes their own administrators.
• Without -keep-passwords, exported accounts arrive without a usable password. Their owners set a new one with Forgot password on the sign-in page, which needs mail to be configured on the new instance and works only for active accounts with a verified email address. pwikit admin create -name <name> can take over such an account, because it has no password.
• With -keep-passwords, accounts keep their passwords and their owners sign in as before. Make one of them an administrator with pwikit admin grant -name <name>.

Importing an export. Restore it into a new instance with pwikit backup restore.

Note A restore always replaces the whole database. Adding a site to an instance that already has sites is not supported: restoring an export over such an instance with -force removes those sites.

On a new instance, the database holds no data yet, whether or not pwikit serve has already run:

pwikit backup restore pwikit-main-20260911-030000.pwbak

Then create an administrator (see above) and start pwikit. If the site moves to a new domain, run pwikit site rebind before starting.

A backup routine

1. Back up every day from the system scheduler, running as the account that owns the data directory. On Linux or macOS, in that account's crontab:

   30 3 * * * /opt/pwikit/pwikit backup create

   On Windows, create a daily task in Task Scheduler that runs C:\pwikit\pwikit.exe backup create under an account that can read the data directory.

2. Copy the files in backups/ to another machine or storage. A backup on the same disk as the instance is lost with that disk.

3. Keep a copy of pwikit.toml and secrets/ in the same place, and update it when they change.

4. Run pwikit backup verify on the copies from time to time.

5. Delete old backups yourself. pwikit never deletes files in backups/, including the before-restore- files.

6. Run pwikit backup create before every upgrade.

Rebuilding the search index

A page enters the site's search index when it is saved. If pages are missing from search results, write them into the index again:

pwikit reindex
pwikit reindex -all

The command reads every page of the site and prints <slug>: <n> pages indexed. It can run while the site is serving. See Command line.

Upgrading pwikit

An instance running as a system service updates itself, and sudo pwikit update updates it by hand. The checks before an update, the automatic rollback when one fails and rolling back by hand are covered in Updating and rolling back.

To replace the executable by hand, for example on an instance that does not run as a service or where pwikit update cannot be used:

1. Stop the service.
2. Back up: pwikit backup create.
3. Replace the pwikit executable with the new one, at the same path. The service refers to that path, so it does not need to be installed again.
4. Start the service.

On start, the new pwikit updates the bundled PostgreSQL in postgres/, keeping the data in pgdata/, and applies the new schema migrations. If the new release carries a new PostgreSQL major version, see Moving to a new PostgreSQL major version. Then run pwikit migrate status to check the result; every line should read applied.

To start without applying migrations, use pwikit serve -no-migrate (or add -no-migrate after -- when installing the service), and apply them later with pwikit migrate up.

Going back to an older pwikit. When every migration of the new release is compatible with older releases, an older pwikit runs on the database as it is, and pwikit migrate status lists those migrations as newer. When one is not, the older pwikit refuses to start and lists it as newer-breaking; use pwikit update rollback, or restore the backup taken before the upgrade using the older pwikit, with -force. See Older releases and the database.

Moving to a new PostgreSQL major version

Bundled PostgreSQL

For an instance running as a system service, sudo pwikit update carries out every step below by itself; see Bundled PostgreSQL major versions. The steps by hand follow.

A PostgreSQL major version cannot read data written by another major version. When a new pwikit carries a newer PostgreSQL than the one that wrote pgdata/, it starts nothing, changes nothing, and stops with an error. To move the data:

1. Stop the service. Put the previous pwikit executable back in place.

2. Run pwikit backup create with the previous executable, and note the file name it prints.

3. Put the new executable in place.

4. Rename pgdata/ to, for example, pgdata.old.

5. Start the service. pwikit creates a new, empty pgdata/.

6. Stop the service.

7. Restore. The new database holds no data yet, so neither -force nor a safety backup is needed:

   pwikit backup restore backups/pwikit-20260911-030000.pwbak

8. Start the service and check the sites. Delete pgdata.old once you are satisfied.

Your own PostgreSQL

pwikit needs PostgreSQL 14 or newer. On an older server, pwikit serve refuses to start. Back up with pwikit backup create, then restore into a newer server with pwikit backup restore <file> -database <new server>, and point pwikit at the new server. Upgrading your own server in place is done with PostgreSQL's own tools.

The secrets directory

secrets/ in the data directory holds values pwikit creates for itself. On Linux and macOS it is created readable only by the account pwikit runs as. Keep it private, and keep a copy with your backups: pwikit backup create does not include it.

File	Present when	Purpose	If it is lost
session-key	No -secret-key or SECRET_KEY is set	Signs sign-in cookies and the links sent by mail. Anyone who can read it can forge a sign-in	pwikit creates a new one. Everyone is signed out, and links already sent by mail stop working
postgres-password	Windows, bundled PostgreSQL	Password pwikit uses to connect to the bundled PostgreSQL. On Linux and macOS the bundled PostgreSQL uses no password and accepts only the account pwikit runs as	pwikit creates a new password that the existing pgdata/ does not accept, and can no longer connect. Put the original file back. Without a copy, move pgdata/ aside, start pwikit to create a new one, stop it, and restore a backup
certs/	-tls=auto	Certificates obtained over ACME and the ACME account key	pwikit requests new certificates when they are next needed

When moving from the Python release, see Migrating from the Python release for what to do with its SECRET_KEY.

Recovering access

Changing a site's domain

When a site's domain no longer reaches the server, for example after a domain change, nobody can open the site or its admin panel to fix it. Change it from the command line; pwikit can keep running:

pwikit site list
pwikit site rebind -slug main -domain wiki.example.net -media-domain files.example.net

-media-domain defaults to the new -domain; pass it again if the site uses a separate media domain. The new domain works at once. If pwikit was serving plain HTTP and the new domain is a public domain name, restart pwikit so it switches to HTTPS.

Granting and revoking superuser

A superuser has every permission regardless of roles and can open the admin panel. When nobody can reach the admin panel, make an existing account a superuser with pwikit admin grant, or use pwikit admin create to create an account or take over an imported account that has no password yet; pwikit admin revoke takes the rights away. See Command line.