alpha

First steps and daily work

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 common guide for all three installation paths — Multipass on a Mac and WSL on Windows (local-dev.md) as well as your own Linux (linux-install.md). It assumes a finished installation with a green shpd-server doctor.

1. Developer dashboard

In development mode a simple web dashboard runs at the server root. It gathers everything you need while testing — no assembling URLs by hand or hunting for data source IDs in the terminal.

Open in your browser:

http://<server-address>/_dev/

In dev mode the root / redirects to /_dev/ automatically, so entering just the server address is enough. In production mode the dashboard doesn't exist — /_dev/... returns 404.

What the dashboard does:

  • List of data sources — all DSs with name, creation date and database. Each has the buttons Open (opens the /{ds-id}/app/ application in a new tab), Logs and Upgrade. The ID can be copied to the clipboard with one click. The list refreshes itself.
  • + New DS — creating a new data source straight from a form (choice of installation module, admin login and password, optionally test data). The progress (ds-create → ds-upgrade → user-create → seed, if chosen) is streamed live into the page; when done, a link leads straight into the new DS.
  • Logs — a log viewer (/opt/shipard/log/shipard.log) with filtering by level, data source and full text, tail -f-style auto-refresh and an expandable record detail including the exception trace.
  • Doctor — runs shpd-server doctor and shows the report.
  • Upgrade All — runs shpd-server ds-upgrade-all on all DSs.

The dashboard is protected only by the mode: development check — it assumes that the development server runs on a trusted network. The orange "DEVELOPMENT MODE" banner at the top is a reminder not to confuse the environment with production.

2. First data source

A data source is one company — its own database and files. You create it in the dashboard:

  1. Click + New DS.
  2. Fill in Name, Admin login and Admin password; you can leave the language, country and installation module as they are.
  3. Tick Seed test data — you get sample persons and mail.
  4. Create Data Source. The progress is printed into the page; at the end there is a link Open data source →.
  5. Sign in with the login and password from step 2.

You will then find the data source in the list on the dashboard under the Open button.

3. After git pull

After every download of a new version:

bash scripts/dev-update.sh

The script always runs composer install, npm install (in frontend/) and npm run build. All steps are idempotent — if nothing changed, they pass in a few seconds.

If table definitions or module cfgItems changed, the data sources need updating too:

shpd-server ds-upgrade-all

(The same can be run with the Upgrade All button in the developer dashboard — see section 1.)

Automation with git hooks (optional)

git config core.hooksPath .githooks

Run it once in the repo. Whoever set the environment up with the dev-bootstrap.sh script has the hooks enabled from it already — dev-update.sh runs by itself after git pull.

4. Dependencies

composer.lock is versioned, so composer install installs the same package versions everywhere. Add a dependency with composer require <package>, change a version with composer update <package>; after editing composer.json by hand (e.g. ext-*) recompute the lock with composer update --lock. composer.json and composer.lock always belong in the same commit.

5. When you want to send changes

The checkout from the guides is cloned over HTTPS — it works even without an SSH key on GitHub. Whoever will push can clone over SSH right away (git@github.com:shipard/shipard.git) or switch the remote later (git remote set-url origin …).

How to send your work — fork, branch and pull request — is described in claude-code-intro.md (chapter 8).

6. Commands

The overview of all shpd-server and shpd-ds commands and the helper scripts is in cli.md. After the basic setup you don't need sudo for ordinary shipard operations.

7. Something not working?

Most problems with getting things running are revealed by the health check:

shpd-server doctor

If it reports a permissions problem:

sudo shpd-server fix-permissions --dry-run    # what would change
sudo shpd-server fix-permissions              # fix it

fix-permissions asks for confirmation before fixing. In a script or via a remote tool, where there is nobody to answer, use --dry-run or, if need be, --force.

You will find the application logs in the developer dashboard under Logs (/_dev/logs/) — with filtering by level and full text — or directly in the file /opt/shipard/log/shipard.log.

When the application reports a schema mismatch after git pull, your table definitions have fallen behind — run shpd-server ds-upgrade-all (or Upgrade All in the dashboard).

Hundreds of lines of Deprecation Notice from composer on Ubuntu 24.04 are harmless — the composer from the packages is older than PHP 8.5. On 26.04 they don't appear.

Still not working? Open an issue on GitHub with the output of shpd-server doctor and the relevant lines from the log — that's how we get to the bottom of it fastest.

And when it's just a quick question you don't want to open an issue for — "is this intended, or a bug?", "how is X done?" — drop by our Discord. There are few of us, but we answer willingly and quickly.