Installation (technical reference)

The Installation page is the canonical walkthrough: it carries the illustrated step-by-step sequence with browser-assistant screenshots, the document-root routes per hosting type, and the troubleshooting list. Follow that page to install. This reference exists for the points that most often cause confusion afterwards, and for operators who want the order without the pictures.

Technical prerequisites (PHP version, database, extensions, cron support) are listed under System requirements.

Order at a glance

The recommended route is the small installer: one install.php that fetches the signed core itself.

1. Create an empty MySQL database and a database user with access to it. Note down host, database name, user and password.
2. Upload install.php via your hosting file manager into the folder Wintertrace should live in (e.g. /wintertrace/).
3. Open that file in the browser (e.g. yourdomain.example/wintertrace/install.php). The installer verifies the signature and unpacks the core.
4. Point the domain at public/ inside that folder (see the section below). After this the installation answers at the domain itself, not at the install.php address.
5. Open the domain — the browser assistant prompts for the database credentials and creates the first admin account. An empty database is sufficient; Wintertrace creates all tables itself.
6. Set up the cron job (see the section after next), then delete install.php.
7. Add drivers and connect their GPS source — see OwnTracks / GPS source setup.

Uploading the complete ZIP by FTP instead of using the installer remains supported; steps 4 onwards are identical.

Why the document root must point to public/

Wintertrace follows the standard public-folder pattern of Laravel: only the public/ directory belongs in the publicly accessible area; the rest of the application code sits outside the web root.

Set your domain’s document root to …/wintertrace/public/, not to …/wintertrace/. Skipping this step exposes application code and configuration files to the public internet.

Whether the panel can do this depends on how the domain is set up. For addon domains and subdomains, cPanel-based hosts expose a document-root field in the domain list. For a main domain, several large providers do not allow the change at all — in that case, move the contents of public/ into the directory your domain already serves and adjust the paths in index.php accordingly. The Installation page lists which route applies to which provider.

The cron job

Wintertrace requires one cron job that runs every minute. The exact URL to call is shown by the assistant at the end of the installation; most hosting control panels provide a graphical cron editor where you can add the job. What this cron job handles during operation, and why no permanently running background process is required, is explained under Updates & cron in operation.

After installation

A brief checklist for the first few minutes:

• Cron job created and running every minute (the dashboard shows the status)
• At least one driver added and their OwnTracks connection verified
• A test service job created and a PDF service record generated
• The automatic update check enabled or disabled as preferred
• The data-retention period set to the desired value

The integrated help inside the software provides additional guidance during setup — it is matched exactly to the installed version.