alpha

Manual installation on Linux

Translation of a guide from the project repository; the Czech original is authoritative. The project's documentation, task files, issues and commits are in Czech — Claude Code reads them for you, and you can ask it in English. Discord is Czech-speaking too, but English works as well.

A guide for someone who has their own Linux server, or Ubuntu directly on their computer. On a Mac and on Windows the path is different — Ubuntu in a virtual machine and a one-command installation following local-dev.md.

Everything spelled out step by step here is done with one command by scripts/dev-bootstrap.sh — it runs steps 1–5 below one after another. This document remains the reference for anyone who wants to see and control every step themselves.

Requirements

  • Ubuntu LTS — 26.04 for a new installation; 24.04 remains supported for existing installations
  • MariaDB ≥ 10.10 — accent-insensitive search uses the uca1400 collation (both supported Ubuntu versions meet the requirement)
  • git (usually preinstalled — if not, sudo apt install git)
  • root access via sudo for the one-time installation

1. Cloning the repository

git clone https://github.com/shipard/shipard.git ~/sw/shpd
cd ~/sw/shpd

Cloning over HTTPS works even without an SSH key on GitHub. How to switch the remote once you want to send changes is in dev-daily.md (section 5).

2. System packages and setup

sudo bash scripts/install-packages.sh --mode=development

The script is idempotent and takes care of:

  • Installing PHP 8.5 with extensions, MariaDB, nginx, composer and Node.js 24 (LTS), unless Node ≥ 22 is already installed. On Ubuntu 24.04 PHP comes from the ondrej/php PPA, on 26.04 from the system repositories. On another system version the script exits with an error before installing anything
  • Creating /opt/shipard/ (data root) and /etc/shipard/ (config root) owned by your user (detected via $SUDO_USER)
  • Configuring a separate PHP-FPM pool shipard running under your user (no group hacks with www-data)
  • A symlink /opt/shipard/shpd → this clone (for the nginx root path)
  • Enabling the nginx site shipard.conf (an existing development.conf is saved as .disabled-TIMESTAMP)

The permission contract is described in docs/operations/permissions.md.

3. Dependencies and frontend build

bash scripts/dev-update.sh

The script runs composer install, npm install (in frontend/) and npm run build. Without the frontend build the /{ds-id}/app/ application would have nothing to serve. Run it as your user, not via sudo. You can ignore the closing prompt to run ds-upgrade-all during the first setup — no data source exists yet. You will run the same script after every git pull (dev-daily.md, section 3).

On Ubuntu 24.04 composer prints hundreds of lines of Deprecation Notice: Constant E_STRICT is deprecated… on every run — the composer from apt (2.7.1) is older than PHP 8.5. The output is harmless, the installation completes fine; on 26.04 it doesn't appear.

4. Server config initialisation

sudo shpd-server server-init --mode=development

Creates /etc/shipard/server.json with the admin DB credentials. The file is owned by root:<your-user> with mode 0640 — root edits it, you read it through group membership.

5. Verification

shpd-server doctor

Prints a report: mode, shipard user, PHP-FPM pool user, path checks, DB connection per DS. Exit 0 = all OK.

If something doesn't match:

sudo shpd-server fix-permissions --dry-run    # preview
sudo shpd-server fix-permissions              # apply

Once doctor is green, open the developer dashboard (dev-daily.md, section 1) — from there you can create your first data source and open the application.

Where next