Quick Start & Workflow Guide

Prepare QGIS

• Create and save your project in QGIS 3.x with all layers styled.
• Define "Map Themes" (a.k.a. Kartteman) for every layer combination you want to cache as a composite.
• Save the project (Ctrl+S) before uploading so the themes are persisted.

Set up the server

• Install OSGeo4W or the standalone QGIS build and configure QGIS_PREFIX, OSGEO4W_BIN, PYTHON_EXE.
• Launch Qtiler with npm start (default http://localhost:3000).
• Optional: install the Windows Service via node service\\install-service.js.

Install apps and plugins

• Open Admin console and use the Install Admin Dashboard to install or update Qtiler plugin ZIP packages.
• The installer reads each plugin manifest, shows license/docs, enables admin consoles, and keeps runtime data under data/<plugin>/.
• Qtiler2Hajk installs the Hajk viewer from a selected GitHub release inside its own admin app, so no separate Hajk server is required.

Dashboard overview

Use the top summary to monitor pending jobs, completed caches, and quick actions like Reload layers or Cache all layers.

Layer controls

Each row exposes play/delete/copy/view buttons plus shortcuts to manual or on-demand caching so operators never leave the dashboard.

1️⃣ Upload or refresh projects

Use Upload project for `.qgs/.qgz` files. Qtiler drops them into qgisprojects/ and extracts layers, CRS, extent, and themes. Manual copies work too—just hit Reload layers.

Importante: Si tu proyecto QGIS utiliza capas en archivos externos (por ejemplo, shapefiles, geopackages, etc.), debes comprimir el proyecto junto con todas sus capas y carpetas relacionadas en un archivo .zip manteniendo la misma estructura de carpetas. Al subir el ZIP, Qtiler extraerá el contenido y el proyecto debe poder encontrar las capas en las rutas relativas originales. Si cambias la estructura al comprimir, QGIS no podrá localizar las capas y el proyecto no funcionará correctamente.

2️⃣ Adjust zoom and extent

Set global min/max zoom and open Show extent map when you need precise bounding boxes. The map supports deep zoom (≈1:100) so you can refine the box in WGS84.

3️⃣ Cache per layer

4️⃣ Cache per theme

The Map Themes section lists every theme found. Use ▶ to generate the composite mosaic (`/wmts/<project>/themes/<theme>/…`). Copy the WMTS URL and preview it in the viewer.

Project-wide cache

Cache all layers launches a batch job that iterates over every layer with the current parameters. The “Running tasks” panel tracks progress live.

Scheduled recache

Open the schedule dialog to configure automatic cache regeneration with three modes: Weekly (select weekdays + time), Monthly (select days of month + time), or Yearly (up to 3 date entries). The server records next run, last result, and history inside the project configuration.

On-demand caching

Qtiler serves tiles directly from QGIS whenever a WMTS/XYZ request misses the cache. Each live render is written back to disk with CRS-aware tile-grid derivation, so manual batch jobs and on-demand traffic stay perfectly aligned. Concurrency is limited to 2 simultaneous render jobs with FIFO queuing.

GIS client integration

• Load the Capabilities URL to register every layer at once.
• Use individual tile URLs when you only need a specific resource.
• Themes are identified as <project>:<theme> and stored under _themes/.

Leaflet viewer

Launch the Leaflet viewer from the eye icon next to each layer or theme. Compare cached tiles against the remote source or preview the cache on its own.

Using Qtiler with Origo Map

For Origo-based portals, point the source to the REST XYZ template (not GetCapabilities) and keep the native CRS. Example source configuration:

{
  "source": "Qtiler_Topografiska_Webbkartan",
  "url": "https://ext.rabbalshedekraft.se/wmts/bakgrunder/Topografiska_Webbkartan/{z}/{x}/{y}.png",
  "type": "XYZ",
  "projection": "EPSG:3006"
}

Example layer entry that references the source:

{
  "name": "bakgrunder_Topografiska_Webbkartan",
  "title": "Topografiska_Webbkartan",
  "group": "background",
  "source": "Qtiler_Topografiska_Webbkartan",
  "type": "XYZ",
  "format": "image/png",
  "visible": true,
  "style": "karta_farg",
  "attribution": "© Lantmäteriet",
  "tileGrid": {
    "alignBottomLeft": false,
    "origin": [ -908609.3787282843, 7825048.779051208 ],
    "resolutions": [
      11426.844956133727, 5713.422478066864, 2856.711239033432,
      1428.355619516716, 714.177809758358, 357.088904879179,
      178.5444524395895, 89.27222621979475, 44.63611310989737,
      22.318056554948686, 11.159028277474343, 5.579514138737172,
      2.789757069368586, 1.394878534684293, 0.6974392673421465,
      0.3487196336710732, 0.1743598168355366, 0.0871799084177683,
      0.04358995420888415, 0.021794977104442077, 0.010897488552221038,
      0.005448744276110519, 0.0027243721380552596
    ]
  }
}

Origo editing via WFS-T (example)

To enable editing in Origo, configure a WFS source (base endpoint) and mark the layer editable. Origo will send Transaction requests (WFS-T) to the source URL via POST.

Example WFS source (note: url is the base endpoint, not a GetCapabilities URL):

{
  "source": "Qtiler_WFS",
  "type": "WFS",
  "url": "http://localhost:3000/wfs?project=po",
  "workspace": "http://localhost:3000/qtiler/po",
  "projection": "EPSG:3006"
}

Example editable layer:

{
  "name": "PO_delar",
  "title": "PO_delar",
  "type": "WFS",
  "source": "Qtiler_WFS",
  "featureType": "PO_delar",
  "geometryName": "geometry",
  "editable": true,
  "attributes": [
    { "name": "GID", "type": "integer", "hidden": true },
    { "name": "NAMN", "type": "string" },
    { "name": "Status", "type": "string" },
    { "name": "Beskrivning", "type": "string" }
  ]
}

Public portal

The /portal page lists all projects accessible to the current user. Each project card shows cached layers, copy buttons (WMTS, WMS, WFS, VectorTiles Style-URL and Source-URL), and viewer links (WMTS, WMS, WFS, VectorTiles) grouped in a Viewers box. Public projects are visible without login.

API keys for GIS clients

When a project is protected by QtilerAuth, all copied URLs automatically include ?api_key=… so GIS clients like QGIS can authenticate tile/map/feature requests. The API key is available after login via /auth/me. WMTS and WMS GetCapabilities also embed the api_key in ResourceURL and OnlineResource so QGIS carries it on every subsequent request.