---
title: "Install and run MapTiler Server on Linux | Guides | Self hosting | Map server"
description: "How to install MapTiler Server on a Linux operating system."
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Install and run MapTiler Server on Linux

This page describes the installation of [MapTiler Server](https://www.maptiler.com/server/) on Linux-based systems.

## Install MapTiler Server

1.  Get the installation package from the [Server download page](https://www.maptiler.com/server/download/). We provide DEB packages for Debian-based Linux distributions (Ubuntu, Debian, Mint, …), RPM packages for RedHat-based distributions (Red Hat, Fedora, CentOS,…) and also universal AppImages.
2.  Run the installation:
    
    -   For DEB packages, use: `sudo dpkg -i maptiler-server-x.x.x.deb`
    -   For RPM packages, use: `sudo rpm -i maptiler-server-x.x.x.rpm`
    -   For AppImages, first allow the package to execute in file properties. (Alternatively, run `chmod u+x maptiler-server-X.X.X-linux.AppImage`.) Then double-click on the package to install it.

### Run directly

When installed, start MapTiler Server:

```text
maptiler-server
```

This command uses the current directory to start MapTiler Server, and generates a random password for the MapTiler Server administration. The password will be printed in the command line. Copy it and use it to log in at `http://localhost:3650/admin`. If you change the default port via a configuration file or environment variable, the address will be `http://localhost:<custom-port>/admin`.

If you want to change the administration password or other settings, run `maptiler-server --help` to list the options.

### Run as a service

Optionally, you can configure and start MapTiler Server as a `systemd` service, so that it keeps running on the machine even after the current user logs out:

```text
sudo maptiler-server-servicify
```

This command starts a script which guides you through setting up MapTiler Server’s working directory (use absolute path), port, and administration password. Then it creates the `systemd` service file and starts the service.

## What’s next

If you’ve just installed MapTiler Server for the first time, we recommend our [Getting Started with MapTiler Server](https://docs.maptiler.com/guides/on-prem/server/getting-started/) to set up map hosting and quickly test it out. You’ll also learn how to set up MapTiler Server for real production deployment [at the end of the guide](https://docs.maptiler.com/guides/on-prem/server/getting-started/#next-steps).

* * *

## Troubleshooting

This section helps solve known issues with installing or running MapTiler Server on Linux.

### MapTiler Server fails to start

In a specific setup, MapTiler Server can fail to start up right after installation or upgrade to a new version, with an error similar to this:

```text
Error: EACCES: permission denied, mkdir '/home/mapserver'
```

This is typically the case if MapTiler Server runs as a `systemd` service under a system user that has limited rights and no home directory.

**What’s happening:** When MapTiler Server starts, it extracts its native dependencies to a cache directory on the local drive. The cache directory is located in the `$HOME` directory of the user that runs MapTiler Server. If the home directory doesn’t exist, or the user doesn’t have write access to it, the server stops right after start.

**How to fix it:** Set the `HOME` variable for the service to a directory the service user can write to. Follow the steps below.

1.  Find out which user runs the service:
    
    ```bash
    systemctl show -p User maptiler-server
    ```
    
2.  Create the directory and make that user its owner. Replace `mapserver` with the user name from the previous step:
    
    ```bash
    sudo mkdir -p /var/cache/maptiler-server
     sudo chown mapserver:mapserver /var/cache/maptiler-server
    ```
    
    The `/var/cache/maptiler-server` directory is a suggestion. You can use any other directory that the service user can write to.
    
3.  Open an override file for the service:
    
    ```bash
    sudo systemctl edit maptiler-server
    ```
    
4.  Add the following lines and save the file:
    
    ```text
    [Service]
     Environment=HOME=/var/cache/maptiler-server
    ```
    
5.  Restart the MapTiler Server service:
    
    ```bash
    sudo systemctl reset-failed maptiler-server
     sudo systemctl restart maptiler-server
    ```
    

The override is stored separately from the service file, so it stays in place when you upgrade MapTiler Server. The same setting works for all MapTiler Server versions.

### Issues with FUSE

MapTilerServer Linux packages use [AppImage](https://en.wikipedia.org/wiki/AppImage) distribution format under the hood, which is based on [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace).

If starting your server results in errors like this:

`fuse: failed to exec fusermount: No such file or directory`

You have to fix your FUSE setup. On reference system, this was easy to fix just with fuse install:

`yum install fuse`

In case you are not able to fix your FUSE setup, you can try to run the server this way

`maptiler-server --appimage-extract-and-run --port=3650`

### Tiles rasterization

This issue specifically happens on **SELinux (RHEL)**. We use RHEL-8.2 as the reference system.

Rasterization library we use in MapTiler Server requires `execheap` memory access. If your server is crashing with error similar to:

`swiftshader-1cba0a9c3a8a1961514ac63cd3091c1a376fe84a/src/Reactor/ExecutableMemory.cpp:352 WARNING: ASSERT(result == 0)`

It means that SELinux policies are preventing MapTiler Server from using this access mode.

Like with any other SELinux issues, checking the systemd journal can be helpful:

`systemctl`

You will find here something like:

_SELinux is preventing maptiler-server from using the execheap access on a process._

You can disable this policy with:

`setsebool -P selinuxuser\_execheap 1`

Or with help from utils you can create a local policy module to allow this access:

`ausearch -c 'maptiler-server' --raw | audit2allow -M my-maptilerserver semodule -i my-maptilerserver.pp`

As the last resort, try turning the SELinux off.