Installation without Docker

It is highly recommended that you deploy using Docker as it is easier install and maintain.

This guide may help the few users who do not wish to use Docker. Please note that this guide may be incomplete or out of date. Additionally, this guide assumes Arch Linux (or Ubuntu 24.04). Although exact instructions for other distributions are different, the steps stay roughly the same. If you meet problem check Dockerfile for server and client. (@dante4 As of 16.07.2024 I were unable to make szurubooru run while using non-EoL libraries, and even with all correct version the system just gives error 500. If you are gonna use szurubooru as private gallery - use docker)

Installing hard dependencies

Szurubooru requires the following dependencies:

• Python (3.8 or later)
• Postgres
• FFmpeg
• node.js

Pacman

user@host:~$ sudo pacman -S postgresql
user@host:~$ sudo pacman -S python
user@host:~$ sudo pacman -S python-pip
user@host:~$ sudo pacman -S ffmpeg
user@host:~$ sudo pacman -S npm
user@host:~$ sudo pip install virtualenv

Apt (Working with Ubuntu 24.04 Noble, untested on others versions) - assumes that you are using VM only for szurubooru, so there is no problem with any system-wide install.

# Import the repository signing key:
sudo apt install curl ca-certificates
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc

# Create the repository configuration file:
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# Update the package lists:
user@host:~$ sudo apt update

# Install the latest version of PostgreSQL:
# If you want a specific version, use 'postgresql-16' or similar instead of 'postgresql'
sudo apt -y install postgresql
sudo apt -y install python3
sudo apt -y install python3-pip
sudo apt -y install ffmpeg
sudo apt -y install python3-virtualenv
sudo apt -y install libheif-dev
sudo apt -y install libavif-dev
mv /usr/lib/python3.12/EXTERNALLY-MANAGED /usr/lib/python3.12/EXTERNALLY-MANAGED.old
pip3 install alembic>=0.8.5
pip3 install certifi>=2017.11.5
pip3 install coloredlogs==5.0
pip3 install heif-image-plugin
pip3 install numpy>=1.8.2
pip3 install pillow-avif-plugin~=1.1.0
pip3 install pillow>=4.3.0
pip3 install psycopg2-binary>=2.6.1
pip3 install pyheif
pip3 install pynacl>=1.2.1
pip3 install pyRFC3339>=1.0
pip3 install pytz>=2018.3
pip3 install pyyaml>=3.11
pip3 install "SQLAlchemy>=1.0.12, <1.4"
pip3 install yt-dlp
pip3 install pillow-avif-plugin
pip3 install freezegun

The reason ffmpeg is used over, say, ImageMagick or even PIL is because of Flash and video posts.

Setting up a database

First, basic postgres configuration:

user@host:~$ sudo -i -u postgres initdb --locale en_US.UTF-8 -E UTF8 -D /var/lib/postgres/data
user@host:~$ sudo systemctl start postgresql
user@host:~$ sudo systemctl enable postgresql

Then creating a database:

user@host:~$ sudo -i -u postgres createuser --interactive
Enter name of role to add: szuru
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n
user@host:~$ sudo -i -u postgres createdb szuru
user@host:~$ sudo -i -u postgres psql -c "ALTER USER szuru PASSWORD 'dog';"

Preparing environment

Getting szurubooru:

user@host:~$ git clone https://github.com/rr-/szurubooru.git szuru
user@host:~$ cd szuru

Installing frontend dependencies:

user@host:szuru$ cd client
user@host:szuru/client$ npm install

(@dante4 - my advice run npm audit fix, it shouldn't break anything, but at least fix a few critical vulnerabilities.) (In case you are used Apt method you may skip below)

npm sandboxes dependencies by default, i.e. installs them to ./node_modules. This is good, because it avoids polluting the system with the project's dependencies. To make Python work the same way, we'll use virtualenv. Installing backend dependencies with virtualenv looks like this:

user@host:szuru/client$ cd ../server
user@host:szuru/server$ virtualenv python_modules # consistent with node_modules
user@host:szuru/server$ source python_modules/bin/activate # enters the sandbox
(python_modules) user@host:szuru/server$ pip install -r requirements.txt # installs the dependencies

Preparing szurubooru for first run

1. Compile the frontend:

   user@host:szuru$ cd client
   user@host:szuru/client$ node build.js

   You can include the flags --no-transpile to disable the JavaScript transpiler, which provides compatibility with older browsers, and --debug to generate JS source mappings.

2. Configure things:

   user@host:szuru/client$ cd ..
   user@host:szuru$ mv server/config.yaml.dist .
   user@host:szuru$ cp config.yaml.dist config.yaml
   user@host:szuru$ vim config.yaml

   Pay extra attention to these fields:

   • data directory,
   • data URL, (@dante4, you need to change postgres to postgresql)
   • database,
   • the smtp section.

3. Upgrade the database:

   user@host:szuru/client$ cd ../server
   user@host:szuru/server$ source python_modules/bin/activate
   (python_modules) user@host:szuru/server$ alembic upgrade head

   alembic should have been installed during installation of szurubooru's dependencies.

4. Run the tests:

   (python_modules) user@host:szuru/server$ pytest

It is recommended to rebuild the frontend after each change to configuration.

Wiring szurubooru to the web server

szurubooru is divided into two parts: public static files, and the API. It tries not to impose any networking configurations on the user, so it is the user's responsibility to wire these to their web server.

The static files are located in the client/public/data directory and are meant to be exposed directly to the end users.

The API should be exposed using WSGI server such as waitress, gunicorn or similar. Other configurations might be possible but I didn't pursue them.

API calls are made to the relative URL /api/. Your HTTP server should be configured to proxy this URL format to the WSGI server. Some users may prefer to use a dedicated reverse proxy for this, to incorporate additional features such as load balancing and SSL.

Note that the API URL in the virtual host configuration needs to be the same as the one in the config.yaml, so that client knows how to access the backend!

Example

In this example:

• The booru is accessed from http://example.com/
• The API is accessed from http://example.com/api
• The API server listens locally on port 6666, and is proxied by nginx or apache
• The static files are served from /srv/www/booru/client/public/data

You can use either nginx or apache to serve your static content and proxy the api server. Choose whichever you prefer, but don't use both.

nginx configuration:

server {
    listen 80;
    server_name example.com;

    location ~ ^/api$ {
        return 302 /api/;
    }
    location ~ ^/api/(.*)$ {
        if ($request_uri ~* "/api/(.*)") { # preserve PATH_INFO as-is
            proxy_pass http://127.0.0.1:6666/$1;
        }
    }
    location / {
        root /srv/www/booru/client/public;
        try_files $uri /index.htm;
    }
}

apache configuration:

<VirtualHost *:80>
    ServerName example.com

    Redirect 302 /api /api/

    ProxyPreserveHost On
    ProxyPass /api/ http://127.0.0.1:6666/
    ProxyPassReverse /api/ http://127.0.0.1:6666/

    DocumentRoot "/srv/www/booru/client/public"
    FallbackResource /index.htm
    AllowEncodedSlashes On
</VirtualHost>

config.yaml:

data_url: 'http://example.com/data/'
data_dir: '/srv/www/booru/client/public/data'

To run the server using waitress:

user@host:szuru/server$ source python_modules/bin/activate
(python_modules) user@host:szuru/server$ pip install waitress
(python_modules) user@host:szuru/server$ waitress-serve --port 6666 szurubooru.facade:app

or gunicorn:

user@host:szuru/server$ source python_modules/bin/activate
(python_modules) user@host:szuru/server$ pip install gunicorn
(python_modules) user@host:szuru/server$ gunicorn szurubooru.facade:app -b 127.0.0.1:6666