Configuring Site Map

Foreman provides an interactive map (Site Map) that helps you navigate your operation, enabling you to pinpoint where problems exist so they can quickly be addressed. For container or building-based deployments, site personal are able to identify which regions are having problems, letting them isolate offending miners that need attention.

If you have an existing system or convention that you're using to track miner locations, please contact our team and we will gladly work with you to get it imported.  For operations that use static IP addresses (ex: - container 1, rack 1, row 1, index 0) or worker names (R1L1N2 - rack 1, level 1, index 2) to represent where a miner is physically located, we will gladly automate this for you from our end so your Site Map is generated automatically. No matter how you're tracking miners, we will get it imported.

Heat Map

When configured to display a Heat Map, Site Map will generate an illustration that outlines where your miners are physically located, while applying a gradient showing how heat is distributed.  In the illustration below, you can see 6 racks inside a container, with the top two rows being hotter than the rest.

A container-based heat map.

Performance Map

When configured to display a Performance Map, Site Map will generate an illustration that outlines where your miners are physically located, clearly displaying which miners are hashing at an appropriate rate and which ones are under-performing.

A container-based performance map.

Core Concepts


Site Map is designed to operate like a grid, with indexes being 0-up.

column 0 column 1 column 2 column 3 column 4
row 0 0, 0 0, 1 0, 2 0, 3 0, 4
row 1 1, 0 1, 1 1, 2 1, 3 1, 4
row 2 2, 0 2, 1 2, 2 2, 3 2, 4
row 3 3, 0 3, 1 3, 2 3, 3 3, 4
row 4 4, 0 4, 1 4, 2 4, 3 4, 4

Inside every component, there is an additional Grid (we'll expand on this a little further down).


The most basic construct that holds miners. A miner, in Site Map, can only be assigned to a Rack.  Every Rack has a name and a position inside of the Grid. The dimensions of the Racks are automatically determined based on where miners are added.

Example: if you had 3 miners, one at (0,0), one at (2, 1), and one at (7,7), you would end up with the following Rack:

Automatic Rack expansion.


An optional construct that can be used to logically collect things together. Groups can hold Racks, but they can also hold other Groups, and they can be infinitely nested.

  • For container-based deployments, there is typically a Group per container.
  • For building-based deployments, there is typically a Group per building.

Example: for a container-based deployment with 10 containers with 6 racks in each, there would be 10 Groups, one for each container, with each Group holding 6 unique Racks.

All Racks within the same Group have the same dimensions. If you need to accommodate different Rack sizes, they would need to go into separate Groups.

As an example, in the illustration below, there is a global Site Map Grid that has Groups for each container (a001, a002, a003..).  Within each Group, there is a new Grid (rack 0, rack 1, rack 2, ....).  And ultimately, inside each Rack, there is a new Grid (top-left miner, miner to the right of that, etc).

Site Map grids.

Creating a Site Map By Example

For the following example, we will assume a container-based deployment, with 2 containers, 4 racks in each, and a total of 40 miners. For simplicity, we'll assume that there are no miners in one of the containers.

When you first access Site Map, you should see the following:

An empty Site Map.

We typically recommend the Upload Layout option. This lets you build a Layout (where Racks and Groups are physically positioned) as a CSV in Excel and then you can import it.  You can do it with the UI above, adding Groups and Racks one-by-one, but it's a little more tedious.

First, click Upload Layout and click the link in the pop-up to download the template.  Open it in Excel or Google Sheets.

Example layout CSV in Sheets.

From here, you can see there are two ways a row is formatted:

  • For Groups: you'll need to fill in the type "group", a name for the group (ex: "container 1"), and its position in the Grid.
  • For Racks: you'll need the Group name that will hold the Rack, the type "rack", a name for the rack (ex: "C1 - 0"), and its position in the Group's Grid.
It is strongly encouraged that Rack names be globally unique.  This will make it easier to select the correct one for dashboard filtering, miner editing, etc.  So rather than "R1", you'd want something like "C1 - R1" for Group C1, Rack 1.

Since we know there are 2 Groups (2 containers) and 8 Racks (4 racks in container 1, 4 racks in container 2), the CSV would look like this:

Completed Layout CSV.

Download the document as a CSV and then import it into Foreman.

Save Sheet as a CSV.
Upload CSV into Foreman.

Once it's uploaded, you should receive a Site Map like this:

Newly created Site Map.

Now that the layout is in place (there are Groups representing the containers, and each Group has 4 Racks), it's time to fill the Racks with miners.  Top-right, click Upload Locations.  You'll have a few options here:

  • Example: generates a sample CSV just to show you how it can be structured for the miners you have (random miner placements into the Racks you've created)
  • Template: generates a template CSV that contains a row for every miner you have in Foreman, but empty values for Rack, row, and index/column.

Since we're filling actual miner placements, the one you pick should be based on what you find to be the most aligned with how you've been tracking things.  If you know locations by IP address, click Template: By IPs.  If you know locations by MAC addresses, click Template: By MACs.

Upload Locations prompt.

The Template will contain every miner in Foreman for your account.  For this example, we'll map locations by MAC address.  Once the CSV is downloaded, open it in Excel or Google Sheets and start filling things in based on where the miners are positioned. This this example operation, the last Rack is the most filled, while the others are generally filled at the top.

Completing the locations CSV by MAC address.

Download the file as a CSV and import it into Site Map.

CSV loaded into the prompt.

You should get a Site Map like this:

The generated, example Site Map.

Every time the locations CSV is uploaded, the existing miner locations are deleted (it's a full rebuild of the miner positioning).  Now that we've created an initial layout, in the Upload Locations prompt top-right, you should always re-download the existing Template and add/remove to that when it's time to modify your Site Map.  This will keep you from losing locations when they're uploaded.  Download template, modify, re-upload.

Stay tuned for more updates! If you have any questions, contact us on Discord, Twitter, or send us an email!

Master Your Mining with Foreman. Try it for free today!

You've successfully subscribed to Foreman Blog
Great! Next, complete checkout for full access to Foreman Blog
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.