Install Pawkey

Installing Pawkey can be done in two ways:

Standalone install

You clone the repository build everything, set up the database by yourself, set up redis by yourself
Docker install

Copy a few files, set config values and deploy

Before you start, you really need:

an 24/7 powered on server with an active network connection
a domain name you can dedicate to your Pawkey instance, resolving to the server
a reverse proxy running on the same machine or another machine on the local network, with valid SSL/TLS certificates for the domain name

Docker install

This is by far the easiest way to install Pawkey, it is recommended to most people.

To install docker refer to the Docker Engine install page

Create the directories you’ll need:

mkdir Pawkey && mkdir Pawkey/.config

Fetch all required examples and enter directory:

wget -O Pawkey/compose.yml https://git.boykissers.com/pawkey/pawkey/raw/branch/dev/compose.yml
wget -O Pawkey/.config/default.yml https://git.boykissers.com/pawkey/pawkey/raw/branch/dev/.config/example.yml
wget -O Pawkey/.config/docker.env https://git.boykissers.com/pawkey/pawkey/raw/branch/dev/.config/docker_example.env
cd Pawkey

Edit docker.env file with your database credentials, this is STRONGLY recommended for security reasons even tho the database server isn’t exposed to the internet

# db settings
POSTGRES_PASSWORD=example-pawkey-pass
POSTGRES_USER=example-pawkey-user
POSTGRES_DB=pawkey

Edit the required config values in .config/default.yml.

url: https://{YOUR DOMAIN NAME}/

Also remember to change the localhost values for Redis and DB, They should match your database and valkey container hostnames so in result this:

db:
  host: db
  port: 5432

  ...

redis:
  host: valkey
  port: 6379

Replace {YOUR DOMAIN NAME} with an actual domain that will be used for this server

Also remember to set proper database credentials in the config matching what you have entered in docker.env

In your compose.yml file, uncomment the env_file it should look like this as the result:

    networks:
      - paws
    env_file:
      - .config/docker.env
    ...

Congratulations, now you can start the containers:

sudo docker compose up -d

Standalone install

Prerequisites:

More than 2GB of free RAM, we recommend at least 4GB
Node.js version 22 or later, with Bun
PostgreSQL version 17 or later
Valkey or Redis 7+
FFmpeg
All the various packages to compile and build C code, and Python (on Debian-style systems, that’s build-essential & python)
Some system libraries and their development headers: pango, cairo, pixman, librsvg (on Debian-style systems, that’s libpango1.0-dev libcairo2-dev libpixman-1-dev librsvg2-2)

We won’t be going in-depth about installing PostgreSQL or Valkey / Redis. Refer to their official documentations or Google.

Create a pawkey user:

adduser --disabled-password --disabled-login pawkey

Start a shell as that user:

sudo -u pawkey bash

(or something like that), then clone the Pawkey repository, and copy the example configuration file:

git clone --recurse-submodules -b dev https://git.boykissers.com/pawkey/pawkey.git Pawkey
cd Pawkey
bun install --frozen-lockfile
cp .config/example.yml .config/default.yml

Edit the required config values in .config/default.yml..

url: {YOUR DOMAIN NAME}
db:
  host: localhost
  port: 5432
  #ssl: false
  # Database name
  db: pawkey

  # Auth
  user: pawkey
  pass: <YOUR PASSWORD>

redis:
  host: localhost
  port: 6379

Build Pawkey:

bun run build

Create the PostgreSQL user and database, either with createuser and createdb or with sudo -u postgres psql and then running these commands inside psql:

CREATE DATABASE pawkey WITH ENCODING = 'UTF8';
CREATE USER pawkey WITH ENCRYPTED PASSWORD '<YOUR_PASSWORD>';
GRANT ALL PRIVILEGES ON DATABASE pawkey TO pawkey;
ALTER DATABASE pawkey OWNER TO pawkey;
q

Replace <YOUR PASSWORD> with the password you want to use, Remember it has to be the same in the default.yml config file.

Then run the migrations:

bun run init

And start Pawkey:

bun run start

If everything worked as it should, you should see lines ending with something like this:

Now listening on port 3000 on https://example.tld

but with a different URL at the end (you did change the url setting in the config file, right?). Stop that process (control-C is enough), and set up a system service for Pawkey.

With systemd

Create a file /etc/systemd/system/pawkey.service containg:

[Unit]
Description=Pawkey Service

[Service]
Type=simple
User=pawkey
ExecStart=/home/pawkey/.bun/bin/bun start
WorkingDirectory=/home/pawkey/Pawkey
Environment="NODE_ENV=production"
TimeoutSec=60
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pawkey
Restart=always

[Install]
WantedBy=multi-user.target

The Bun binary location can be different on your system, check it with where bun.

Then:

sudo systemctl daemon-reload
sudo systemctl enable pawkey
sudo systemctl start pawkey

After that, sudo systemctl status pawkey should show that it’s running. Now you can open your instance URL in your browser, to complete the setup.

Updating Pawkey

For update instructions, look at Updating Pawkey page.

Troubleshooting

Something doesn’t work? Refer to the Troubleshooting Guide

Proxy Setup

Refer to the Proxy Setup page