terraink README

The project's README from github.com/yousifamanuel/terraink. As one markdown file: README.md.

Terraink

Note: Terraink is still in development. Every feedback is appreciated. This is an open-source project, and community contributions are very welcome.

License & Trademark Notice: This project is licensed under AGPL-3.0 and includes trademark protections. See the License and Trademark sections for details.

Features

Custom city map posters for any location in the world, powered by real OpenStreetMap data
Smart geocoding — search for any city or region by name, or enter coordinates manually
Rich theme system — choose from dozens of curated themes or build your own custom color palette
Detailed map layers — roads, water bodies, parks, and building footprints with per-layer styling
Typography controls — set city/country display labels in one of nine bundled, self-hosted typefaces
High-resolution export — download a print-ready poster as PNG, PDF, or layered SVG at any defined dimension

Data Providers and Mapping Stack

Map data: OpenStreetMap contributors
Tiles: OpenMapTiles
Tile hosting: OpenFreeMap
Geocoding: Nominatim
Map renderer: MapLibre

User Interface

Terraink web UI

Showcase

Featured Examples

Featured showcase example 1 Featured showcase example 2

License

As of April 3rd 2026, all new changes to this repository are licensed under AGPL-3.0. Code released before that date remains under the MIT License.

The hosted Terraink service includes attribution and branding as part of the user interface.

If you deploy or modify the open-source version, you are responsible for complying with the AGPL-3.0 license, including preserving license and copyright notices.

For access to the hosted version with additional features and support, see Terraink Business or contact: [email protected].

Trademark

Terraink™ is a trademark of Yousuf Amanuel. An application for registration has been filed with the German Patent and Trade Mark Office (DPMA). This filing establishes priority rights under the Paris Convention, allowing international trademark registration to be pursued within six months of the original filing date. The Terraink logo, visual identity, and branding assets are copyright © 2026 Yousuf Amanuel. All rights reserved.

Unauthorized use of the Terraink name in connection with similar software, map services, or related commercial products may be restricted. For licensing inquiries, contact [email protected].

See TRADEMARK.md for details.

Run

bun install
bun run dev

Environment

Check .env.example for available variables. They are optional for most local work and should not be set during testing unless a specific case requires them.

Build

bun run build

Deploy with Docker (Self-Hosting)

1) Build and run with Docker Compose

Create .env from .env.example (or set APP_PORT directly in your shell), then run:

docker compose up -d --build

This serves the app on http://localhost:7200 by default.

To change the exposed host port:

Linux/macOS:

APP_PORT=80 docker compose up -d --build

PowerShell:

$env:APP_PORT=80
docker compose up -d --build

2) Stop the deployment

docker compose down

3) Optional: build and run without Compose

docker build -t terraink:latest .
docker run -d --name terraink -p 7200:80 --restart unless-stopped terraink:latest

Contributing

The contribution guidelines are meant to keep Terraink easy to extend, review, and maintain over time. They are here to support a durable architecture, not to add unnecessary friction.

Read CONTRIBUTING.md before opening a PR.

Branch from dev and target dev only. Do not open PRs against main.
Fill out the pull request template completely when you open a PR.
Keep contributions clean, modular, and aligned with the existing architecture.
Avoid hard-coded values when constants, configuration, or reusable abstractions are more appropriate.
AI-assisted coding is allowed, but submissions must be reviewed, refined, and intentionally engineered before review.

Attribution

Map data: © OpenStreetMap contributors, licensed under ODbL
Tile schema: © OpenMapTiles, licensed under ODbL
Tile hosting: OpenFreeMap
Geocoding: Nominatim / OpenStreetMap data
Map renderer: MapLibre GL JS, licensed under BSD-3-Clause

Acknowledgment

Terraink was inspired by MapToPoster by Ankur Gupta, originally released under the MIT license. Terraink is an independent reimplementation built from scratch using Bun, React, and TypeScript, and has since evolved significantly beyond the original concept.

Star History

Searching Database…

4.2K ·GitHub

这是什么？

Terraink 是一个地图海报引擎，使用真实的 OpenStreetMap 数据，为世界上任何城市或地点生成独特且可定制的地图海报。

这是桌面应用，还是需要我自己托管的网页应用？

它是一个用 Bun、React 和 TypeScript 构建的自托管网页应用，部署后在浏览器中打开即可设计海报。

如何让它跑起来？

把 .env.example 复制为 .env，然后用 Docker Compose 构建并运行，应用默认会通过一个暴露的端口提供服务（可通过 APPPORT 修改）。

部署之前我需要准备什么？

自行托管需要 Docker 和 Docker Compose；如果想手动构建并运行，可以用 bunx --bun vite，这需要安装 Bun；在本地使用时环境变量是可选的。

如果我自行托管，许可证方面有什么要注意的？

自 2026 年 4 月起，所有新代码都采用 AGPL-3.0 许可证，Terraink 名称受商标保护，因此如果你部署或修改它，就必须遵守 AGPL-3.0，包括保留许可证和版权声明。

它为海报提供了哪些自定义选项？

你可以从数十个精选主题中选择，也可以创建自定义配色；可以控制显示哪些地图图层（道路、水系、公园、建筑物轮廓）及其样式；还可以用内置的九款字体之一设置城市/国家标签。

海报可以导出为哪些格式？

高分辨率海报可以按任意设定尺寸导出为 PNG、PDF 或分层 SVG，可直接用于打印。

地图渲染和搜索靠什么实现？

地图数据来自 OpenStreetMap，经由托管在 OpenFreeMap 上的 OpenMapTiles 瓦片提供，使用 MapLibre GL JS 渲染，地理编码由 Nominatim 处理。

Terraink 是为什么而开发的？

它的灵感来自 Ankur Gupta 开发的 MIT 许可项目 MapToPoster，但它是使用 Bun、React 和 TypeScript 从零开始的独立重新实现，此后已远远超出最初的概念。

What are similar projects?

maptoposter, map-to-poster, rankme.fast, documenso, osiris, convert, github-release-monitor, open-pencil-cloud

Which topics is it in?

poster, openstreetmap, png, webapp, wallpaper, geospatial, maps, generative-art, creative-tools, reactjs, typography, bun

Creator: yousifamanuel
Size: 36.8 MB
Stars: 4.2K
Updated: CommitSep 24 Releasev0.4.9Jul 17
Age: 8mo
Commits · 90 Days