Support the ARM64 Linux headless build of Factorio

Factorio publishes a linux-arm64 headless build from 2.1.18. On ARM64
Linux the host now downloads that build, refuses versions older than
2.1.18 that are not already installed, and finds the binary in bin/arm64
or bin/x64, whichever is present.

The host builds the download URL from the version instead of using
headlessUrl from the controller, so the version list on the wire stays
the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-11-18 11:14:54 +00:00
1 parent 35f9609865
commit 5aaea1f213
7 files changed
+167 -15

No files matched your search

+3 -1
View File
@@ -11,7 +11,9 @@ RUN apt update \
&& apt install -y wget \
&& mkdir /clusterio
WORKDIR /clusterio
RUN wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz
ARG TARGETARCH
RUN if [ "$TARGETARCH" = "arm64" ]; then build=linux-arm64; else build=linux64; fi \
&& wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/$build && tar -xf factorio.tar.gz && rm factorio.tar.gz
# Copy project files into the container
COPY . .
+4
View File
@@ -129,6 +129,10 @@ Check out all our of decisions for [node, factorio, and operation support](/docs
3. Optionally copy the generated systemd service files in `systemd` folder to `/etc/systemd/system/`.
Hosts on Linux download the headless build of Factorio as needed.
On ARM64 (aarch64) Linux this only works for Factorio 2.1.18 and later, which is the first version Factorio published an ARM64 headless build for.
Older versions have to be installed manually, for example the x64 build run through an emulator.
**Ubuntu with Docker**
+2 -1
View File
@@ -592,7 +592,8 @@ Defaults to "latest".
### factorio.executable_path
Path relative to the Factorio installation directory of the executable to run.
If null the path is auto detected, which is `bin/x64/factorio` on Linux and Windows and `MacOS/factorio` on macOS.
If null the path is auto detected, which is `MacOS/factorio` on macOS and otherwise `bin/x64/factorio` or `bin/arm64/factorio`, whichever exists.
When both exist the one matching the CPU is used.
Only needed in special setups.
Defaults to null.
+44 -9
View File
@@ -1,6 +1,6 @@
// Factorio Server interface
import fs from "node:fs/promises";
import { type FSWatcher, createWriteStream, watch as fsWatch, writeFileSync } from "node:fs";
import { type FSWatcher, createWriteStream, existsSync, watch as fsWatch, writeFileSync } from "node:fs";
import child_process from "child_process";
import dgram from "dgram";
import path from "path";
@@ -182,6 +182,19 @@ async function downloadAndExtractTar(url: string, targetDir: string) {
}
}
/**
* Factorio Linux build architecture matching this host
*
* @returns "arm64" on ARM64 Linux, otherwise "x64".
*/
function factorioArch(): lib.FactorioHeadlessArch {
return process.platform === "linux" && process.arch === "arm64" ? "arm64" : "x64";
}
function hasArm64Headless(version: lib.FullVersion) {
return lib.integerFullVersion(version) >= lib.integerFullVersion(lib.minimumArm64HeadlessVersion);
}
// Factorio downloads in progress by target directory, shared by every server in the process
const downloadsInProgress = new Map<string, Promise<void>>();
@@ -202,14 +215,27 @@ export async function checkForUpdates(
logger: lib.Logger = lib.logger,
) {
const latestVersion = availableVersions
.filter(v => (
targetVersion === "latest" || v.version === targetVersion || v.version.startsWith(targetVersion)
))
const matchesTarget = (version: string) => (
targetVersion === "latest" || version === targetVersion || version.startsWith(targetVersion)
);
const arch = factorioArch();
const matching = availableVersions.filter(v => matchesTarget(v.version));
const latestVersion = matching
.filter(v => arch !== "arm64" || hasArm64Headless(v.version))
.sort((v1, v2) => versionOrder(v1.version, v2.version))
[0];
if (!latestVersion) {
if (matching.length && arch === "arm64" && process.platform === "linux") {
const installed = await listFactorioVersions(factorioDir);
if (!installed.direct && ![...installed.versions].some(matchesTarget)) {
throw new Error(
`Factorio ${targetVersion} has no ARM64 Linux headless build to download, ` +
`ARM64 builds start at ${lib.minimumArm64HeadlessVersion}. Install it manually ` +
`or use version ${lib.minimumArm64HeadlessVersion} or later.`
);
}
}
return;
}
@@ -242,7 +268,7 @@ export async function checkForUpdates(
logger.info(`A newer version of factorio is available (${v}), waiting for download...`);
} else {
logger.info(`A newer version of factorio is available (${v}), starting download...`);
download = downloadAndExtractTar(latestVersion.headlessUrl, dst).finally(() => {
download = downloadAndExtractTar(lib.factorioHeadlessUrl(v, arch), dst).finally(() => {
downloadsInProgress.delete(dst);
});
downloadsInProgress.set(dst, download);
@@ -1734,8 +1760,8 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
/**
* Get Factorio binary path
*
* Get the path to the factorio binary depending on the configuration
* and or the platform (MacOS support)
* Get the path to the factorio binary depending on the configuration,
* the platform (MacOS support) and the bin/x64 or bin/arm64 dir present
*
* @returns Path to factorio binary
*/
@@ -1746,7 +1772,16 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
if (process.platform === "darwin") {
return this.dataPath("..", "MacOS", "factorio");
}
return this.dataPath("..", "bin", "x64", "factorio");
// Prefer the native build, fall back to whichever one is installed
const arches = factorioArch() === "arm64" ? ["arm64", "x64"] : ["x64", "arm64"];
for (const arch of arches) {
const binary = this.dataPath("..", "bin", arch, "factorio");
// eslint-disable-next-line node/no-sync
if (existsSync(binary)) {
return binary;
}
}
return this.dataPath("..", "bin", arches[0], "factorio");
}
/**
+19 -1
View File
@@ -14,6 +14,24 @@ export const ExternalFactorioVersionSchema = Type.Object({
export type ExternalFactorioVersion = Static<typeof ExternalFactorioVersionSchema>;
/** CPU architectures Factorio publishes Linux headless builds for */
export type FactorioHeadlessArch = "x64" | "arm64";
/** First Factorio version with an ARM64 Linux headless build */
export const minimumArm64HeadlessVersion = "2.1.18";
/**
* Download URL of the Linux headless build of a Factorio version
*
* @param version - Factorio version to download.
* @param arch - CPU architecture of the build.
* @returns URL redirecting to the tarball.
*/
export function factorioHeadlessUrl(version: string, arch: FactorioHeadlessArch = "x64") {
const build = arch === "arm64" ? "linux-arm64" : "linux64";
return `https://www.factorio.com/get-download/${version}/headless/${build}`;
}
/**
* Fetch all factorio versions that support headless
*
@@ -60,7 +78,7 @@ function parseFactorioVersions(html: string): ExternalFactorioVersion[] {
versions.set(version, {
version: version,
stable: kind === "stable",
headlessUrl: `https://www.factorio.com/get-download/${version}/headless/linux64`,
headlessUrl: factorioHeadlessUrl(version),
});
}
}
+81 -2
View File
@@ -328,6 +328,54 @@ describe("host/server", function() {
});
});
describe(".binaryPath()", function() {
const _platform = process.platform;
const _arch = process.arch;
const installDir = path.join("temp", "test", "binary-path");
function serverFor(dir) {
return new hostServer.FactorioServer(
installDir, writePath, path.join(installDir, dir, "data"), "2.1.24", { rconPassword: "" }
);
}
function mockHost(platform, arch) {
Object.defineProperty(process, "platform", { value: platform });
Object.defineProperty(process, "arch", { value: arch });
}
before(async function() {
await fs.rm(installDir, { force: true, recursive: true });
const layouts = [["none", []], ["x64", ["x64"]], ["arm64", ["arm64"]], ["both", ["x64", "arm64"]]];
for (const [dir, arches] of layouts) {
await fs.mkdir(path.join(installDir, dir, "data"), { recursive: true });
for (const arch of arches) {
await fs.mkdir(path.join(installDir, dir, "bin", arch), { recursive: true });
await fs.writeFile(path.join(installDir, dir, "bin", arch, "factorio"), "");
}
}
});
afterEach(function() {
mockHost(_platform, _arch);
});
const binary = (dir, arch) => path.join(installDir, dir, "bin", arch, "factorio");
for (const [platform, arch, dir, expected] of [
["linux", "x64", "both", "x64"],
["linux", "arm64", "both", "arm64"],
["linux", "x64", "arm64", "arm64"],
["linux", "arm64", "x64", "x64"],
["linux", "x64", "none", "x64"],
["linux", "arm64", "none", "arm64"],
["win32", "arm64", "none", "x64"],
]) {
it(`should pick bin/${expected} on ${platform} ${arch} with ${dir} installed`, function() {
mockHost(platform, arch);
assert.equal(serverFor(dir).binaryPath(), binary(dir, expected));
});
}
it("should use MacOS/factorio on darwin", function() {
mockHost("darwin", "arm64");
assert.equal(serverFor("both").binaryPath(), path.join(installDir, "both", "MacOS", "factorio"));
});
});
describe("._handleIpc()", function() {
it("should emit the correct ipc event", async function() {
let waiter = events.once(server, "ipc-channel");
@@ -760,15 +808,46 @@ describe("host/server", function() {
stable: false,
version: "0.1.0",
headlessUrl: "test3",
}], logger), new Error("Failed to fetch test1: -1 Fetch called"));
}], logger), /Failed to fetch \S+\/get-download\/0\.1\.5\/headless\/linux64/);
assert.equal(fetchCalledWith, "test1");
assert.equal(fetchCalledWith, "https://www.factorio.com/get-download/0.1.5/headless/linux64");
assert.ok(logLine !== null);
assert.ok(logLine.endsWith("starting download..."));
});
});
/* eslint-enable no-loop-func */
}
describe("on ARM64 Linux", function() {
const _arch = process.arch;
const factorioDir = path.join("test", "file", "factorio");
beforeEach(function() {
Object.defineProperty(process, "platform", { value: "linux" });
Object.defineProperty(process, "arch", { value: "arm64" });
});
afterEach(function() {
Object.defineProperty(process, "arch", { value: _arch });
});
const versions = [
{ stable: false, version: "2.1.25", headlessUrl: "test1" },
{ stable: true, version: "2.1.17", headlessUrl: "test2" },
{ stable: true, version: "0.1.5", headlessUrl: "test3" },
];
it("should download the linux-arm64 build", async function() {
await assert.rejects(hostServer.checkForUpdates(factorioDir, "latest", versions), /Fetch called/);
assert.equal(fetchCalledWith, "https://www.factorio.com/get-download/2.1.25/headless/linux-arm64");
});
it("should reject versions older than 2.1.18", async function() {
await assert.rejects(
hostServer.checkForUpdates(factorioDir, "2.1.17", versions),
/Factorio 2.1.17 has no ARM64 Linux headless build to download, ARM64 builds start at 2.1.18/
);
assert.equal(fetchCalledWith, null);
});
it("should accept an older version that is already installed", async function() {
await hostServer.checkForUpdates(factorioDir, "0.1", versions);
assert.equal(fetchCalledWith, null);
});
});
describe("concurrent downloads", function() {
const versions = [{ stable: true, version: "0.1.5", headlessUrl: "test1" }];
+14 -1
View File
@@ -1,10 +1,23 @@
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import { fetchFactorioVersions } from "@clusterio/lib";
import { factorioHeadlessUrl, fetchFactorioVersions } from "@clusterio/lib";
import { slowTest, externalTest } from "../../common.js";
describe("FactorioVersions", function() {
describe("factorioHeadlessUrl", function() {
it("should return the linux64 build by default", function() {
assert.equal(
factorioHeadlessUrl("2.1.24"), "https://www.factorio.com/get-download/2.1.24/headless/linux64"
);
});
it("should return the linux-arm64 build for arm64", function() {
assert.equal(
factorioHeadlessUrl("2.1.24", "arm64"),
"https://www.factorio.com/get-download/2.1.24/headless/linux-arm64",
);
});
});
describe("fetchFactorioVersions", function() {
const originalFetch = global.fetch;