versatiles 3.5.0

A toolbox for converting, checking and serving map tiles in various formats.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# VersaTiles Server Configuration

The VersaTiles server uses a YAML configuration file to control its behavior. This file lets you customize the server's network settings, security policies, static content, and tile sources. You provide the configuration file when starting the server with the `--config` option:

```shell
versatiles serve --config server_config.yaml
```

Below is a complete example of a server configuration file with detailed explanations. All sections and fields are optional; default values are used when fields are omitted.

## Tile Sources

Tile sources can be specified as:

- **Local files**: `.versatiles`, `.mbtiles`, `.pmtiles`, or `.tar` containers
- **Remote URLs**: HTTP/HTTPS URLs to tile containers
- **VPL pipelines**: `.vpl` files for advanced tile processing (see `versatiles help pipeline`)

Example with different source types:

```yaml
tiles:
  - name: osm
    src: osm.versatiles
  - name: remote
    src: https://example.org/tiles.pmtiles
  - name: processed
    src: pipeline.vpl
```

VPL (VersaTiles Pipeline Language) allows you to define complex tile processing pipelines that can merge, filter, transform, and recompress tiles from multiple sources. For detailed VPL documentation, run `versatiles help pipeline`.

```yaml
# Optional HTTP server configuration
server: 
  
  # Optional IP address to bind to
  # Defaults to "0.0.0.0"
  ip: 0.0.0.0
  
  # Optional HTTP server port
  # Defaults to 8080
  port: 8080
  
  # Optional flag to prefer faster compression over smaller size
  # Defaults to false (smaller compression)
  minimal_recompression: false
  
  # Optional flag to disable the `/api` endpoints
  # Defaults to false (enabling the API)
  disable_api: false

# Optional Cross-Origin Resource Sharing (CORS) settings
cors: 
  
  # Allowed origins for CORS requests
  # Defaults to `["*"]` (all origins allowed).
  # Supports:
  # - `*` to allow all origins
  # - Exact origins like `https://example.com`
  # - Globs at the start of the domain like `*.example.com`
  # - Globs at the end of the domain like `example.*`
  # - Regular expressions enclosed in slashes like `/domain\..*$/`
  allowed_origins: 
    - "https://example.org"
    - "*.example.net"
  
  # Optional duration for preflight cache in seconds
  # Defaults to 86400 (1 day)
  max_age_seconds: 86400

# Optional extra HTTP response headers to add to every response
# For example, cache control or timing headers
extra_response_headers: 
  Cache-Control: public, max-age=86400, immutable
  CDN-Cache-Control: max-age=604800

# Optional list of static content sources
static: 
  - # Path to static files, archive (e.g., .tar.gz) or directory containing assets
    src: ./frontend.tar
    
    # Optional URL prefix where static files will be served
    # Defaults to root ("/")
    prefix: /

# Optional list of tile sources
tiles: 
  - # Optional name identifier for this tile source
    # Tiles will be available under `/tiles/{name}/...`
    # Defaults to the basename (e.g., "osm" for "osm.versatiles")
    name: osm
    
    # Path or URL to the tile data source
    # Can be a local file (.versatiles, .mbtiles, .pmtiles, .tar),
    # a remote URL, or a VPL pipeline file (.vpl).
    src: osm.versatiles
```