A server on a Windows computer · Joripo documentation

A Windows computer can run a complete Joripo server: the engine, a PostgreSQL database in Docker, and the file store on a local or dedicated drive. The packaging of this path (an installer, a service that starts with Windows) is being finalised; today it is started from the engine's folder, as below.

What it needs

Windows 10 or 11, with long paths switched on. A form ID can be long, and it appears twice in a form definition's path, which can pass Windows' old 260-character limit; without long paths a Windows server cannot save such a form. Switch on Enable Win32 long paths (or LongPathsEnabled in the registry), an administrator's change.
Docker Desktop, for the local PostgreSQL database.
The engine's Python environment, created once in the engine's folder.
Node.js, if the engine should open every uploaded form in its own form engine before deploying it (recommended). Without it, that check is skipped and the compiler's checks remain.
A drive for the storage root with room to grow, and room for backups (see Backups and restore).

Configuration

The engine reads its settings from its .env file (copy the example file beside it). The ones that matter first:

Setting	What it is
`DATABASE_URL`	The PostgreSQL database. On Windows write `127.0.0.1`, not `localhost`: Windows tries IPv6 first and the driver hangs.
`STORAGE_ROOT`	The file store, for example a folder on a dedicated drive. The older name `SERVER_ROOT` works too.
`SECRET_KEY`	Signs sign-ins and seals the garbling vault. See Keys and secrets.
`APP_ENV`	`production` on a server people use.
`PUBLIC_BASE_URL`	The address phones and links use, when it is fixed. A quick tunnel sets it for you.

The .env file holds secrets: keep it out of any shared folder and out of version control.

Starting it

Start Joripo (the Start Joripo.bat launcher) brings up Docker and the database, then the engine, checking each step first, and opens the console at http://localhost:8000. Leave its window open; closing it stops the engine.

The engine listens on 127.0.0.1 only: this computer reaches it, nobody else on the network does, and phones reach it through an HTTPS tunnel. To let phones on the same Wi-Fi connect directly over plain http, start it with -Lan; it then warns that passwords typed over that address cross the network unencrypted. See Reaching the server from the field.

First run

Create the first organisation. Open http://localhost:8000. An empty database opens Set up Joripo: create the first organisation and its owner.

Make yourself the server's maintainer, from the engine's folder:

python scripts\set_maintainer.py [email protected]

It asks for a password twice (at least 12 characters) and writes only its scrypt hash to a file in the home folder of the Windows account that runs the server, outside the data and the code. Sign in at /admin/login; the first sign-in sets up the authenticator code.

Publish the apps. Upload Joripo Collect and Joripo Desktop for your server on Server administration › Apps, so your team can install them from /app and /desktop.

Logs

The engine writes its log to joripo.log in its folder. Server administration › Server health shows the recent warnings and errors, kept across restarts.

When the computer is off

A server on a laptop is reachable only while the computer is on and the engine is running. Phones keep working offline and send what they hold when the server is back; web forms do not open while it is down.