Merge pull request #1228 from bbassie/feature/arm-headless

Support the ARM64 Linux headless build of Factorio
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-11-18 13:33:28 +00:00
commit b8e96989af
7 files changed
+222 -16

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.
+40 -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,15 @@ 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";
}
// Factorio downloads in progress by target directory, shared by every server in the process
const downloadsInProgress = new Map<string, Promise<void>>();
@@ -202,14 +211,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 => process.platform !== "linux" || lib.hasFactorioHeadless(v.version, "linux", arch))
.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 +264,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, "linux", arch), dst).finally(() => {
downloadsInProgress.delete(dst);
});
downloadsInProgress.set(dst, download);
@@ -1734,8 +1756,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 +1768,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");
}
/**
+52 -2
View File
@@ -1,5 +1,5 @@
import { Static, Type } from "@sinclair/typebox";
import { FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js";
import { FullVersion, FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js";
const ARCHIVE_URL = "https://factorio.com/download/archive/";
@@ -9,11 +9,61 @@ const ARCHIVE_URL = "https://factorio.com/download/archive/";
export const ExternalFactorioVersionSchema = Type.Object({
stable: Type.Boolean(),
version: FullVersionSchema,
/** @deprecated Linux x64 only, use {@link factorioHeadlessUrl} instead. */
headlessUrl: Type.String(),
});
export type ExternalFactorioVersion = Static<typeof ExternalFactorioVersionSchema>;
/** Platforms Factorio may publish headless builds for, named as in Node's process.platform */
export type FactorioHeadlessPlatform = "linux" | "win32";
/** CPU architectures Factorio may publish headless builds for, named as in Node's process.arch */
export type FactorioHeadlessArch = "x64" | "arm64";
/** First Factorio version with an ARM64 Linux headless build */
export const minimumArm64HeadlessVersion = "2.1.18";
/**
* Check if Factorio publishes a headless build of a version
*
* @param version - Factorio version to check.
* @param platform - Platform of the build.
* @param arch - CPU architecture of the build.
* @returns true if the build can be downloaded.
*/
export function hasFactorioHeadless(
version: FullVersion,
platform: FactorioHeadlessPlatform,
arch: FactorioHeadlessArch,
) {
if (platform !== "linux") {
return false;
}
return arch === "x64" || integerFullVersion(version) >= integerFullVersion(minimumArm64HeadlessVersion);
}
/**
* Download URL of the headless build of a Factorio version
*
* @param version - Factorio version to download.
* @param platform - Platform of the build.
* @param arch - CPU architecture of the build.
* @returns URL redirecting to the archive.
* @throws Error if Factorio has no headless build for the platform and arch.
*/
export function factorioHeadlessUrl(
version: FullVersion,
platform: FactorioHeadlessPlatform,
arch: FactorioHeadlessArch,
) {
if (!hasFactorioHeadless(version, platform, arch)) {
throw new Error(`Factorio ${version} has no headless build for ${platform} ${arch}`);
}
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 +110,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, "linux", "x64"),
});
}
}
+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" }];
+40 -1
View File
@@ -1,10 +1,49 @@
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import { fetchFactorioVersions } from "@clusterio/lib";
import { factorioHeadlessUrl, fetchFactorioVersions, hasFactorioHeadless } from "@clusterio/lib";
import { slowTest, externalTest } from "../../common.js";
describe("FactorioVersions", function() {
describe("hasFactorioHeadless", function() {
for (const [version, platform, arch, expected] of [
["0.17.79", "linux", "x64", true],
["2.1.17", "linux", "arm64", false],
["2.1.18", "linux", "arm64", true],
["2.1.24", "win32", "x64", false],
["2.1.24", "win32", "arm64", false],
]) {
it(`should return ${expected} for ${version} ${platform} ${arch}`, function() {
assert.equal(hasFactorioHeadless(version, platform, arch), expected);
});
}
});
describe("factorioHeadlessUrl", function() {
it("should return the linux64 build for x64", function() {
assert.equal(
factorioHeadlessUrl("2.1.24", "linux", "x64"),
"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", "linux", "arm64"),
"https://www.factorio.com/get-download/2.1.24/headless/linux-arm64",
);
});
it("should throw for Windows", function() {
assert.throws(
() => factorioHeadlessUrl("2.1.24", "win32", "x64"),
new Error("Factorio 2.1.24 has no headless build for win32 x64"),
);
});
it("should throw for linux arm64 before 2.1.18", function() {
assert.throws(
() => factorioHeadlessUrl("2.1.17", "linux", "arm64"),
new Error("Factorio 2.1.17 has no headless build for linux arm64"),
);
});
});
describe("fetchFactorioVersions", function() {
const originalFetch = global.fetch;