Local Deployment (Docker)

For advanced users who want full control and features

💡 Looking for something simpler? Check out the Windows App - a standalone executable with no Docker setup required!

Local deployment using Docker allows you to use all the features that may be disabled on the public version due to hosting limitations and large amount of users. If you deploy the tool locally, you can generate maps of any size with the highest speed limited only by your hardware.

This guide is for advanced users comfortable with Docker, command line tools, and system configuration. If you're new to these technologies, consider using the Windows App instead.

🎛️ Key Features

Presets System

The Presets feature allows you to:

• 📁 Store Multiple Configurations - OSM files, DEM files, Main Settings, and Generation Settings

• 🚀 One-Click Apply - Load complete map setups instantly

• 💾 Save from My Maps - Convert successful generations into reusable presets

• 🔄 Build Template Libraries - Create collections of proven configurations

Advanced Data Management

• My Maps - Complete map library management and organization

• Data Directory - Full control over your map generation assets

• Custom Resources - Custom OSM and Custom DEM files

System Requirements

• CPU with at least 4 cores

• Virtualization must be enabled in BIOS/UEFI settings

• Virtual Machine Platform feature must be enabled on Windows

• 8 GB RAM for 2 km maps, 16 GB RAM for 4-8 km maps, 32 GB RAM for larger maps

• SSD storage (will work very slow on HDD)

• Windows 10/11 22H2 or later / Linux / MacOS

• Docker must be installed and running

• Either Hyper-V (Windows Pro only) or WSL 2 must be enabled

Prerequisites

Before deployment, make sure that the following components are in place:

1. Check that the Docker is installed and running properly:

# Shows Docker version.
docker --version

# Launches a test container and removes it after execution.
docker run --rm hello-world

1. Make sure that you increased the limit for Docker resources (CPU, Memory) in Docker settings. Otherwise the containers will be stopped upon generation.

2. Check that the Powershell is installed and running properly:

# Shows PowerShell version.
$PSVersionTable.PSVersion

# Launches a test PowerShell command.
Write-Host "Hello, World!"

*️⃣ PowerShell is required for automated deployment, but you still can launch the containers manually with basic terminal without PowerShell installed.

1. Install the corresponding version of the Giants Editor.

*️⃣ Note: you must use the specific version that matches the game installation. Not just major versions, such as, GE 9.X for FS22 and GE 10.X for FS25, but also the exact minor versions, that matches the game version. Otherwise, the editor will crash or have errors and glitches.

Deployment

There are different ways to deploy the tool locally, depending on your needs and preferences. For most users, it's recommended to use the automated Setup Wizard. However, you can choose other approaches as well.

Setup Wizard

Skill level: 🟢 Requires: PowerShell

The easiest way to deploy Maps4FS locally is using our automated setup wizard. You can run it directly from PowerShell:

powershell -ExecutionPolicy Bypass -Command "iex (iwr 'https://raw.githubusercontent.com/iwatkot/maps4fs/main/setup-wizard.ps1' -UseBasicParsing).Content"

This command will:

• Download the latest setup wizard

• Check that Docker is installed

• Allows download and install Docker if not

• Checks if the Docker daemon is running or launches it if not

• Checks for the containers of old versions and removes them if necessary

• Checks if required ports are available

• Creates necessary directories and files

• Deploys the containers with all the necessary configurations

• Opens the web interface in your default browser

Using Docker Compose

Skill level: 🟡 Requires: Docker Compose

If you want better control of the deployment such as mounts to specific directories or whatever, you can use the Docker Compose. Download the latest docker-compose.yml file from the repository here manually or use this command to download it directly from PowerShell:

# Download docker-compose.yml
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/iwatkot/maps4fs/main/docker-compose.yml" -OutFile "docker-compose.yml"

# Launch Docker Compose.
docker-compose -p maps4fs up -d

If you don't need to make any changes you can launch the docker compose file directly from the PowerShell:

# Launch docker-compose directly from GitHub
powershell -ExecutionPolicy Bypass -Command "iwr 'https://raw.githubusercontent.com/iwatkot/maps4fs/main/docker-compose.yml' -OutFile 'docker-compose.yml'; docker-compose -p maps4fs up -d"

Manual Deployment

Skill level: 🟡 Requires: Docker

If you prefer to set up the containers manually, you can use the following commands:

# Backend API container
docker run -d --pull=always -p 8000:8000 --name maps4fsapi -e USERPROFILE="$env:USERPROFILE" -v $env:USERPROFILE/maps4fs/mfsrootdir:/usr/src/app/mfsrootdir -v $env:USERPROFILE/maps4fs/templates:/usr/src/app/templates -v $env:USERPROFILE/maps4fs/defaults:/usr/src/app/defaults -v /var/run/docker.sock:/var/run/docker.sock iwatkot/maps4fsapi

# Frontend UI container  
docker run -d --pull=always -p 3000:3000 --name maps4fsui -e USERPROFILE="$env:USERPROFILE" -v $env:USERPROFILE/maps4fs/mfsrootdir:/usr/src/app/mfsrootdir -v $env:USERPROFILE/maps4fs/templates:/usr/src/app/templates -v $env:USERPROFILE/maps4fs/defaults:/usr/src/app/defaults -v /var/run/docker.sock:/var/run/docker.sock iwatkot/maps4fsui

*️⃣ Remember that you can set the preferable directory to mount as well as specify the needed port or even deploy the specific version of the container.

Upgrade

To upgrade Maps4FS to the latest version, you have several options:

🆕 One-Click Upgrade (Recommended)

The easiest way to upgrade! When a new version is available, an upgrade button will automatically appear in the top-right corner of the Maps4FS interface.

Requirements for one-click upgrade:

• ✅ Docker socket access (/var/run/docker.sock mounted)

• ✅ USERPROFILE environment variable available

• ✅ Proper container configuration

How it works:

1. 🔍 Maps4FS automatically checks for new versions

2. 🔔 Upgrade button appears when update is available

3. 🖱️ Click the button to start automatic upgrade

4. 🔄 Containers are updated automatically in the background

This feature is available for Docker Compose and Manual Deployment when properly configured.

Using Setup Wizard

The Setup Wizard automatically handles upgrades. Simply run the same command again:

powershell -ExecutionPolicy Bypass -Command "iex (iwr 'https://raw.githubusercontent.com/iwatkot/maps4fs/main/setup-wizard.ps1' -UseBasicParsing).Content"

The wizard will detect existing containers, remove old versions, and deploy the latest release.

Manual Docker Commands

For Docker Compose or Manual Deployment, stop and remove existing containers first:

# Stop and remove existing containers
docker stop maps4fsapi maps4fsui
docker rm maps4fsapi maps4fsui

Then follow your original deployment method to install the latest version.

Usage

After deployment, you can access the web interface of Maps4FS by opening your browser and navigating to http://localhost:3000. The backend API will be accessible at http://localhost:8000.

By default, the following directories are mounted and used:

• C:/Users/YourUsername/maps4fs/mfsrootdir - Shared working directory between backend and frontend (maps and cache).

• C:/Users/YourUsername/maps4fs/templates - Templates and schemas directory for API.

• C:/Users/YourUsername/maps4fs/defaults - 🆕 Presets system - Multiple OSM files, DEM files, and settings configurations.

🎯 New Presets Structure: The defaults directory now supports the Presets system with four subdirectories:

• defaults/osm/ - Multiple OpenStreetMap data files

• defaults/dem/ - Multiple Digital Elevation Model files

• defaults/main_settings/ - Core map configuration presets

• defaults/generation_settings/ - Advanced generation option presets

Learn more about the Data Directory structure, Presets, and Map Templates.

Troubleshooting

If you encounter any issues during the deployment or usage of Maps4FS, we recommend using our interactive help tool first.

🎯 Interactive Help Tool (Recommended)

Try the Interactive Help Tool first: http://localhost:3000/help

This tool will:

• 🔍 Diagnose local deployment issues - Docker problems, container issues, port conflicts

• 🛠️ Guide you through solutions step-by-step

• 📋 Generate complete reports in markdown format for support requests

• 🎯 Save time with automated troubleshooting

💡 Note: If you can't access the local help tool (because containers aren't running), you can use the public version at maps4fs.xyz/help or follow the manual steps below.

---

Manual Troubleshooting Steps

If the interactive help tool isn't accessible, follow the steps outlined below to understand what's wrong.

Check Docker

Make sure Docker is installed and running properly on your machine.

docker --version

As a result, you should see the installed version of Docker. Then, launch the sample container that will be removed automatically after a few seconds.

docker run --rm hello-world

*️⃣ If any of the above commands fail, that means you have issues with Docker and need to ensure that is properly installed and configured.

Check the containers

You need to ensure that both frontend and backend containers are exist and running properly. The two containers being used are:

Container name	Default port	Image name	Description
maps4fsapi	8000	iwatkot/maps4fsapi	Backend API container
maps4fsui	3000	iwatkot/maps4fsui	Frontend UI container

Use the following commands to filter by specific container names or image names:

# Filter by container name.
docker ps --filter "name=maps4fs"

The expected output should be something like:

CONTAINER ID   IMAGE                     COMMAND                  CREATED         STATUS         PORTS                    NAMES
abc123def456   iwatkot/maps4fsapi       "uvicorn app.main:app…"   5 minutes ago   Up 5 minutes   0.0.0.0:8000->8000/tcp   maps4fsapi
def456abc123   iwatkot/maps4fsui        "npm start"               5 minutes ago   Up 5 minutes   0.0.0.0:3000->3000/tcp   maps4fsui

*️⃣ If the command itself failed, that means you have issues with Docker and need to ensure that is properly installed and configured.

If containers stopped

If you don't see both containers in the output, maybe they have stopped or failed to start. First of all, you need to know the exit code of the container.

# Check exit code of backend API container
docker inspect maps4fsapi --format='{{.State.ExitCode}}'

# Check exit code of frontend UI container
docker inspect maps4fsui --format='{{.State.ExitCode}}'

Common exit codes include:

Exit Code	Meaning
0	Success
1	General error
137	Container killed (out of memory)

Then, check the logs of the containers:

# Check logs of backend API container
docker logs maps4fsapi

# Check logs of frontend UI container
docker logs maps4fsui

To save the logs into file, you can use the following commands:

# Save logs of backend API container
docker logs maps4fsapi > maps4fsapi.log

# Save logs of frontend UI container
docker logs maps4fsui > maps4fsui.log

If the logs do not contain any errors, but simply indicate that the process was terminated, you may be facing a resource limitation issue and it's recommended to check the system resource usage (CPU, RAM) during the container runtime. If the logs contain errors, but they are unclear, it's recommended to ask for help in the Discord.

Docker events

You can monitor Docker events to get real-time information about container lifecycle changes. Use the following command:

docker events

To save the events for last 24 hours into a file, you can use the following command:

docker events --since 24h > docker_events.log

Docker exit code 137

The most common exit code indicating that the container was killed due to out of memory (OOM) issues. For large maps, the generator may be processing gigantic images and/or meshes, which may lead to high RAM usage. In this case, you need to increase the memory limit for the containers, refer to the official Docker documentation for more information on how to do this.

If containers running

If both containers are running, but you still facing issues, please check that both of them are accessible.

# Check if backend API is accessible and returns JSON response:
Invoke-WebRequest -Uri http://localhost:8000/info/version -UseBasicParsing

The expected response should be a JSON object like:

{"version":"2.2.7"}

For the UI container use the following command:

# Check if frontend UI is accessible and returns HTML response:
Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing

The expected response should be the HTML content of the frontend UI.

*️⃣ If commands fail, that means that the backend API is not accessible or not running properly. Please check the container logs and status as described in the troubleshooting steps above.

If you still have issues

Recommended approach:

1. 🎯 Try the Interactive Help Tool at http://localhost:3000/help (if containers are running)

2. 📋 Use the generated markdown from the tool for your support request

3. 💬 Ask for help in the Discord server or see Getting Help guide

Manual approach:

• Make sure you've followed all the troubleshooting steps above

• Include all relevant logs and outputs in your request

*️⃣ Requests without sufficient information may be ignored. The Interactive Help Tool ensures you provide all necessary details.

Checklist before asking for help

• My machine meets the system requirements.

• I am attaching the hardware specifications and information about the OS (including version) with this request.

• I have checked the Docker version and run the hello-world container.

• I am attaching outputs of both commands with this request.

• I have ensured that Docker is properly installed and configured.

• I have checked the status of both containers (API and UI) and they are running.

• I am attaching outputs of both commands with this request.

• I have checked the logs for both containers.

• I am attaching both log files with this request.

• I have checked the resource usage (CPU, RAM) during the container runtime.

• I have checked the Docker events for any relevant information.

• I am attaching the Docker events log file with this request.

• I have checked accessibility of both containers (API and UI).

• I am attaching the outputs of both accessibility checks with this request.