# Welcome

**LOD** (Levels of Detail) is a thin map tile proxy with **in-memory caching** and a slim authentication backend built with **performance** in mind. It will sit in front of any tile server and will aggressively cache tiles in memory, optionally storing them in a configured Redis cluster for faster fetching later. **LOD** is cluster-aware and uses Redis message queueing for intra-cluster communication when multiple instances are deployed together.

LOD is written in Go 1.19 using [fiber](https://github.com/gofiber/fiber). TOML is used for configuration. Go templates are used for templating. Internal in-memory caching is built upon the [bigcache](https://github.com/allegro/bigcache) library by [allegro](https://github.com/allegro).

{% hint style="warning" %}
These docs are for **LOD** **v0,** which is in active development. **LOD v1** is coming soon. See the [**Roadmap**](https://lod.tile.fund/roadmap) for more info.
{% endhint %}

### Getting Started

Download a build from the releases page or just run:

```bash
$ go install github.com/tile-fund/lod@latest
```

{% hint style="warning" %}
NOTE: You'll need the GEOS library installed on your system to use some of LOD's more advanced cache invalidation and priming functionality.
{% endhint %}

```bash
Flags:
  --conf  Path to TOML configuration file. Default: config.toml
  --dev   Whether to enable developer mode. Default: false
  --debug Optional comma separated debug flags. Ex: foo,bar,baz
  --help  Shows this help menu.
Usage:
  lod [--conf config.toml] [--dev]
```

Or just use our Docker image!

You can create your own `Dockerfile` that adds a `config.toml` from the context into the config directory, like so:

```docker
FROM tilefund/lod:0.8.0
COPY /path/to/your_config.toml /opt/lod_cfg/config.toml
CMD [ "/opt/lod", "--conf", "/opt/lod_cfg/config.toml" ]
```

Alternatively, you can specify something along the same lines with Docker run options:

```bash
$ docker run -v /path/to/lod-config:/opt/lod_config -p 1337:1337 tilefund/lod:0.8.0 --conf /opt/lod_config/config.toml
```

### Core Principles

* Lightweight, parallel, and non-blocking
* Tileserver agnostic (Martin, Tegola, flat file NGINX, etc.)
* Tile format and content agnostic
  * Vector ([Mapbox Vector Tiles](https://github.com/mapbox/vector-tile-spec) or [other vector formats](https://wiki.openstreetmap.org/wiki/Vector_tiles))
  * Raster (PNG/JPG/TIFF)
  * And [more](https://wiki.openstreetmap.org/wiki/Tiles)...
* Supports [XYZ (Slippy) ](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)and [TMS](https://wiki.openstreetmap.org/wiki/TMS) tile indexing schemes

## License

**LOD** is licensed under the GNU Affero General Public License 3 or any later version at your choice. See [*COPYING*](https://github.com/tile-fund/lod/blob/master/COPYING) for details.

## More Tile Resources

* <https://wiki.openstreetmap.org/wiki/Category:Tiles_and_tiling>
* <https://wiki.openstreetmap.org/wiki/Tile_servers>
* <https://github.com/mapbox/awesome-vector-tiles>
* <https://docs.mapbox.com/vector-tiles/reference/>