DEV Community: Noan

How to georeference a map with QGIS

Noan — Wed, 08 Apr 2026 09:29:22 +0000

This tutorial is for you if you have a map you obtained from some website or some book, you need to produce a .tiff file which is a localised version of your a mapping. E.g. to display it in a mapping system such as leaflet but you do not know how to do it. You mya have read notes about projection systems, but the calculous got complicated and you may not even know what projection system your map is using.
QGIS can help you to geo reference a map even without knowing the projection system.

Geo-reference the image

Once you have installed QGIS:

Open the GeoReferencer tool

Load your image

Click on add a point

Find a point of your map from which you can deduce the coordinate, e.g. a building, a place, a confluence of 2 rivers, a specific point on a coast. You can find its coordinates on OpenStreetMap. Fill in the coordinates (X = longitude, Y = latitude).

Find another point and repeat step 4 at least once, the more location you fill, the more precise the georeferencing.
Click on Transformation Settings.

In transformation type, choose Linear projection which is the simplest geo referencing algorithm and is relevant if your map is not distorted. This algorithm may produce unexpected result if your image is distorted (e.g. if it's a picture of a book the page may be curved on the corners). To optimize the result you can find out about other algorithms to find the most appropriate to your map.
Click Run, QGIS will produce a .tiff file in the same folder as your input image. Which is your geo referenced map.

(Optional) Verify your geo-referencing with OpenStreetMap

After you have runned the geo-referencing process QGIS should open the .tiff file. You may want to open it over a map to make sure the geographic elements of the maps stand at the right coordinates.
In order to create the OpenStreetMap layer in QGIS you can

Add an XYZ layer
Choose OpenStreetMap as the source, add it

Make sure to move your image layer on top of the OSM layer to view it
Right-click on the image layer and in the layer properties choose an opacity lower than 100% to see both your image and OpenStreetMap
You may now compare your image geo referenced with the real map

How to create a blog with GitLab Pages

Noan — Wed, 08 Apr 2026 08:41:37 +0000

If you to need to host a blog, GitLab can help to build and host it with GitLab Pages. In this tutorial we'll use GitLab CI and Jekyll to deploy your blog. This is the configuration I use for my personal website.

Prerequisites

Have a project hosted on GitLab

1. Create and build your blog locally

1.1 Create a homepage and an article

cd my-project

In index.html

---
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>My first blog</title>
    </head>

    <body>
        <section>
            <h2>
            <!-- {{ link | absolute_url}} is a 'Liquid' expression Jekyll will interpret to prefix the link with the url and the base_url previously defined  -->
                <a href="{{'/articles/my-first-article.html' | absolute_url}}">My first article</a>
            </h2>
        </section>
    </body>
</html>

The 2 dashed lines at the top of the markdown file define your Front Matter, this is a .yml configuration section for your page we will talk about later

In articles/my-first-article.html

---
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My first article</title>
</head>
<body>
    <p>Hi Mom</p>
</body>
</html>

In Gemfile

source "https://rubygems.org"

gem "jekyll"

In _config.yml

baseurl: /<name_of_your_gitlab_project>

1.2 Test locally with Jekyll

So you do not have to run the GitLab pipeline to ensure your blog's code does not have bugs.

This tutorial has been tested on Ubuntu 24.04 (some commands in this section may not be adapted to your OS)
Useful links:

Install Jekyll on Windows

Install Jekyll on macOS

Install ruby (via rbenv) and Jekyll

# Install dependencies to run ruby
sudo apt update && sudo apt install -y git curl build-essential libz-dev libffi-dev libssl-dev libyaml-dev

# Clone rbenv and install it
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
~/.rbenv/bin/rbenv init
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Then find the latest stable release of ruby with

rbenv install -l

We will remember it as RUBY_VERSION, replace RUBY_VERSION in the following commands with the version you have found.

# Install and use a ruby environment
rbenv install RUBY_VERSION
rbenv global RUBY_VERSION

# Install bundler and install the blog's dependencies
gem install bundler
bundle install

Serve the blog

bundle exec jekyll serve

Your changes are visible at http://localhost:4000/

1.3. Ignore the files Jekyll has created

In your .gitignore

_site/

2. Use GitLab CI to build and deploy your website

In your .gitlab-ci.yml

image: ruby:RUBY_VERSION

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

And push

git add .
git commit -m "Gitlab pages setup"
git push

The pipeline deploying your project is visible on your project's home on GitLab, under Build/Pipelines.

3. Visit your website

On your project's home on GitLab, navigate to Deploy/Pages to see your website's URL.

Uncheck Use unique domain if you want your blog to be accessible from a more user-friendly URL, but keep in mind HTTPS won't work for.gitlab.io domains if your username or project name contains a dot (you can still set up your own domain).

4. (Optional) Write your blog in Markdown

One major feature of Jekyll is to translate Markdown files into an HTML website.

4.1. Tell Jekyll you'll be using Markdown

In _config.yml

markdown: kramdown
baseurl: /<name_of_your_gitlab_project>

4.2. Change your article to Markdown

Remove the file articles/my-first-article.html

In articles/my-first-article.md

---
---
# Hi Mom
Hope you're fine

Run bundle exec jekyll build and you should find your translated HTML file under _site/articles/my-first-article.html

<h1 id="hi-mom">Hi Mom</h1>

<p>Hope you’re fine</p>

This page is missing basic HTML structure and metadata. We could write our Markdown inside an HTML canvas, but this would lead in repetitions in our code, let's take advantage of Jekyll layout features.

4.3 Define a layout for your posts

In _layouts/default.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>{{ page.title }}</title>
    <!--
        You may add any stylesheet or script you'd like to use
        <link rel="stylesheet" href="'/assets/main.css'"> 
        -->
</head>

<body>
    <header>
    <nav><a href="{{'/' | absolute_url}}">My first blog</a></nav>
    </header>
    <main>
        {{ content }} <!-- Your content will go here -->
    </main>

</body>

</html>

And then edit the file articles/my-first-article.md and make use of the Front Matter

---
title: My first article
layout: default
---

# Hi Mom

Hope you're fine

Test it with bundle exec jekyll build or bundle exec jekyll serve, once you're confident in your changes push them and let GitLab do the rest.

5. (Optional) Preview your changes before publishing them

In a development process, we usually want to review changes we have made before publishing them. This could also apply to a blog.

5.1. Prevent the pages' publication if the pipeline does not belong to the main branch

In .gitlab-ci.yml

image: ruby:RUBY_VERSION

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # This rule prevents the pages job from being executed for a commit that is not made on the main branch

5.2. Create another job only for MR which will upload a preview version of the blog

Add a file named generate_pipeline_config.sh

# Outputs a configuration which will later be used by jekyll to generate the website and make links that points to the website-as-artifact generated
echo "url: https://$CI_PROJECT_NAMESPACE.gitlab.io"
echo "baseurl: /-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public"

And make it executable

chmod +x generate_pipeline_config.sh

In .gitlab-ci.yml

stages: # This is new
  - staging
  - pages
pages:
  stage: pages
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # This rule prevent the pages job to be executed for commit not made on the main branch
  artifacts:
    paths:
      - public

preview-pages: # This is almost the same job, as it is not named 'pages' the job will not publish its result on GitLab Pages
  stage: staging
  script:
    - gem install bundler
    - bundle install
    # The 2 following lines are modified
    - ./generate_pipeline_config.sh > pipeline_config.yml
    - bundle exec jekyll build -c _config.yml,pipeline_config.yml -d public # pipeline_config.yml redefines some variable from _config.yml
  rules:
    - if: $CI_MERGE_REQUEST_IID # This rule to execute the job only if it is part of a merge request
  environment:
    name: $CI_COMMIT_REF_NAME
    # The environment is a link to the artifact produced by the pipeline
    url: https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html
  artifacts:
    paths:
      - public

Create an MR with your changes.
The environment section tells GitLab you have deployed something at a certain URL.
On the MR overview it suggests the reader to visit the website you have just deployed.

Some links will not work in the preview. The artifact browsing server we are using is not made to be a web server. Contrary to the GitLab Pages server it will not return /index.html if you ask for /, neither will it return /articles/my-first-article.html you requested /articles/my-first-article. You can choose between writing exclusively explicit links or rewrite the url in your browser when browsing the preview

How to build and serve custom simplified maps with OpenMapTiles

Noan — Tue, 13 Jan 2026 08:32:21 +0000

If you need to display a map on your website and do not plan to use online mapping services such as MapTiler or Mapbox, you may want to use OpenMapTiles to generate and serve custom tiles. This approach is also useful when you are not interested in all the features a map can display.
In this tutorial, we will create a map featuring only water, such as coastlines, lakes and rivers.
This tutorial was tested on Ubuntu 24.04.

Prerequisites

Osmium: a tool used to process OpenStreetMap data.
The OpenMapTiles repository cloned on your computer.
Docker, to run the OpenMapTiles containers.
The build-essential package (to run the make command).

1. Download the source data

OpenStreetMap provides an up-to-date export of the entire planet.

Pay attention to the licenses of the tools and data used. For OpenStreetMap and OpenMapTiles, proper attribution must be displayed on your map, for example: © OpenMapTiles © OpenStreetMap contributors

The planet.osm.pbf file is about 85GB. This is very large and can take hours to process even you are when only interested in the water data. During development, it is recommended to use an extract from GeoFabrik covering a smaller region that you know well.
In my case, I used the file bretagne.osm.pbf and then the file france.osm.pbf. They can be processed in a few seconds or minutes.

A .osm.pbf file is a compressed format for OpenStreetMap data, if you decompress it with the command osmium cat <your-region>.osm.pbf --output <your-region>.osm you will find that the .osm file is an XML file listing nodes, ways, and polygons. The documentation for this format is available on the OpenStreetMap wiki

2. Extract the relevant data

Since we are only interested in water data, the process can be sped up by reducing the input file size. Let's filter out everything that is not related to water:

osmium tags-filter <your-region>.osm.pbf  rw/waterway rw/water -o water.osm.pbf

3. Generate the vector tiles

At the root of the OpenMapTiles repository, edit the file openmaptiles.yaml to comment out all layers except those related to water:

tileset:
  layers:
    - layers/water/water.yaml
    - layers/waterway/waterway.yaml
    # All other layers are commented out
    # - layers/landcover/landcover.yaml
    # - layers/landuse/landuse.yaml
    # - layers/mountain_peak/mountain_peak.yaml
    # - layers/park/park.yaml
    # - layers/boundary/boundary.yaml
    # - layers/aeroway/aeroway.yaml
    # - layers/transportation/transportation.yaml
    # - layers/building/building.yaml
    # - layers/water_name/water_name.yaml
    # - layers/transportation_name/transportation_name.yaml
    # - layers/place/place.yaml
    # - layers/housenumber/housenumber.yaml
    # - layers/poi/poi.yaml
    # - layers/aerodrome_label/aerodrome_label.yaml
  name: OpenMapTiles
  version: 3.15.0
  id: openmaptiles
  description: "A tileset showcasing all layers in OpenMapTiles. https://openmaptiles.org"
  ...

Next, edit the .env file to specify the zoom levels to generate:

...
# Which zooms to generate with make generate-tiles-pg
MIN_ZOOM=0
MAX_ZOOM=10
...

Move the water.osm.pbf you generated earlier into the data/ directory

mkdir openmaptiles/data/
mv water.osm.pbf openmaptiles/data/

Now run OpenMapTiles to generate the tiles:

cd openmaptiles
./quickstart.sh water

Under the hood, this process will:

Populate a PostGIS database with map features. Note that the database already contains Natural Earth data for low zoom levels. At low zoom levels, coastlines in the resulting map will come frome Natural Earth data.
Create views and functions in this database responsible for querying each layer for each zoom level.
Query the PostGIS database to create a file named tiles.mbtiles. It is a SQLite database containing vector tile data for each (x, y, z) coordinate.

4. Serve the tiles

make start-tileserver

And visit http://localhost:8080

Or if you want to serve the tiles on a server without the whole OpenMapTiles project

# Make sure you have Node.js version 18.17.0 or later installed
npm install -g tileserver-gl
tileserver-gl --file tiles.mbtiles

Conclusion

In this tutorial, we have introduced techniques for generating simple vector maps: where to retrieve the data, how it can be filtered with Osmium, how OpenMapTiles processes it to generate vector tiles, and finally how tileserver-gl can serve them (although it is not production-ready on its own).

From here, you may then want to style your map with Maputnik, explore the user interactions provided by MapLibre, or dig deeper into the transformations performed by OpenMapTiles for each layer.