Installation and building
Packages for Windows, Linux and macOS, the web version, and building from source.
Released versions are on the releases page
with a SHA256SUMS file; how they are made is in releasing.
Building from source requires a recent stable Rust toolchain (rustup update stable);
releases are built with the version pinned in .github/workflows/ci.yml. The installer
scripts below and trunk build --release also need
cargo-about
(cargo install cargo-about@0.9.3 --locked --features cli) for
THIRD-PARTY-LICENSES.html, which every package contains next to LICENSE-MIT and
LICENSE-APACHE.
Desktop (Windows / Linux / macOS)
cargo run --release -p openecraft
On Linux you need the usual windowing / dialog libraries, e.g. on Debian/Ubuntu:
sudo apt install libxkbcommon-dev libgtk-3-dev libwayland-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev
A project file given on the command line is opened at start (openecraft plant.oec).
Windows installer
OpenECraft-<version>-setup.exe installs the editor with a Start menu entry, without
administrator rights (or for all users in Program Files), in English, German, French or
Spanish after the Windows language. Optional: the parts manager, the command line / MCP
server (added to the PATH on request), the parts and project servers, a desktop
shortcut, and opening .oec / .oecz / .oecp files by double-click. It is uninstalled in
Settings › Apps; projects and settings are kept. CI builds it on every push (artifact
openecraft-windows-installer); locally it needs
Inno Setup 6 (winget install JRSoftware.InnoSetup):
powershell -ExecutionPolicy Bypass -File installer/windows/build.ps1 # → target/installer/
The binaries link the C runtime statically, so no Visual C++ redistributable is needed.
For unattended installation (software distribution) run the setup with
/VERYSILENT /SUPPRESSMSGBOXES, add /ALLUSERS for all users and select parts with
/COMPONENTS="main,partsmanager,cli,servers" and /TASKS="fileassoc,addtopath".
With WINDOWS_SIGN_CERT=<.pfx file> and WINDOWS_SIGN_PASSWORD the script signs the
programs, the setup and the uninstaller (signtool of the Windows SDK); otherwise they are
unsigned and SmartScreen asks for confirmation on first run (see releasing).
installer/icon.py draws the application icon (assets/icon.png, assets/icon.ico,
assets/icon.icns, assets/icon.svg).
Linux packages
installer/linux/build.sh builds the packages for the architecture of the build machine
into target/installer/. Each contains the editor and the parts manager (with menu
entries in English, German, French and Spanish), the command line / MCP server and the
parts and project servers. With deb, rpm, Flatpak and tar.gz .oec / .oecz / .oecp files open
by double-click.
bash installer/linux/build.sh # tar.gz, deb, rpm, AppImage
bash installer/linux/build.sh flatpak snap # sandboxed packages
| Package | File | Install | Build tool |
|---|---|---|---|
| Debian, Ubuntu | openecraft_<version>_amd64.deb | sudo apt install ./openecraft_*.deb | dpkg-dev |
| Fedora, RHEL, openSUSE | openecraft-<version>-1.x86_64.rpm | sudo dnf install ./openecraft-*.rpm | rpmbuild |
| Any distribution | OpenECraft-<version>-x86_64.AppImage | chmod +x, start it | Debian or Ubuntu, patchelf, zsync, appimagetool and its runtime (downloaded, checksums verified) |
| Any distribution | OpenECraft-<version>-x86_64.flatpak | flatpak install --user OpenECraft-*.flatpak | flatpak-builder |
| Any distribution | openecraft_<version>_amd64.snap | sudo snap install --dangerous openecraft_*.snap | snapcraft |
| Any distribution | OpenECraft-<version>-linux-x86_64.tar.gz | ./install.sh (to ~/.local) | tar |
The programs are openecraft, openecraft-parts-manager, openecraft-cli,
openecraft-parts-server and openecraft-project-server. In the AppImage they are
started with OpenECraft-*.AppImage parts-manager|cli|parts-server|project-server …, in
the Flatpak with flatpak run --command=openecraft-cli io.github.nilres.OpenECraft …
and in the snap as openecraft.cli, openecraft.parts-manager, … CI builds them on every
push (artifacts openecraft-linux-packages, openecraft-flatpak, openecraft-snap);
deb, rpm, AppImage and tar.gz are built on Debian 12 and run with glibc 2.36 or newer.
The AppImage carries the window libraries that are not on every system (xkbcommon,
Xcursor, Xi: appimage_libs in installer/linux/build.sh); the build refuses one that
needs another library or a newer glibc than the programs. It also carries update
information for AppImageUpdate and similar tools: the latest GitHub release of the
repository that built it (GITHUB_REPOSITORY, otherwise nilres/OpenECraft), whose
OpenECraft-<version>-x86_64.AppImage.zsync the build writes next to the AppImage
(APPIMAGE_UPDATE_INFO sets other update information, an empty value none).
The desktop entries, MIME types and AppStream data (io.github.nilres.OpenECraft) are
in installer/linux/; a new version needs a <release> in the metainfo file.
macOS disk image
installer/macos/build.sh builds OpenECraft-<version>-macos.dmg (macOS 11 or newer,
universal binaries for Apple silicon and Intel) with the apps OpenECraft and
OpenECraft Parts Manager; drag them to Applications. The command line and the servers
are in the app bundle:
rustup target add aarch64-apple-darwin x86_64-apple-darwin
bash installer/macos/build.sh # → target/installer/
/Applications/OpenECraft.app/Contents/MacOS/openecraft-cli help
Without MACOS_SIGN_IDENTITY the apps are signed ad hoc, so Gatekeeper asks for
confirmation on first start (System Settings › Privacy & Security › Open Anyway). With
a Developer ID certificate (MACOS_SIGN_IDENTITY="Developer ID Application: …") and a
notarytool keychain profile (MACOS_NOTARY_PROFILE, MACOS_NOTARY_KEYCHAIN when it is
not in the login keychain) the image is signed and notarized.
Projects are opened with File › Open project; opening them by double-click in the Finder is not
supported yet. CI builds the image on every push (artifact openecraft-macos-dmg).
Updates
When it starts, the editor asks GitHub in the background for the latest release
(https://api.github.com/repos/nilres/OpenECraft/releases/latest); without a connection
it carries on without a message. A newer release is downloaded, checked against the
SHA256SUMS of the release and installed:
| Installation | Update |
|---|---|
| Windows setup | OpenECraft-<version>-setup.exe runs silently (/SILENT) when the editor is closed, in the folder and with the components of the installation; Restart and update starts the editor again afterwards |
| AppImage | the AppImage file is replaced at once; the new version starts next time (AppImageUpdate and similar tools update it too) |
| macOS app | OpenECraft.app (and OpenECraft Parts Manager.app next to it) are replaced from the disk image at once |
| deb, rpm, Flatpak, Snap, tar.gz, own build | the status bar only tells of the new version and links its release page |
The status bar shows the download and Restart and update; File › Help › Check for
updates looks again and reports every outcome. Settings › Updates switches the check
at start off, the environment variable OPENECRAFT_NO_UPDATE_CHECK (any value) does so
for all users of a computer. The web version has no update of its own.
Docker images of the servers
The parts server and the project server are also published as Docker images on
every release and on every push to master, built by installer/docker/Dockerfile
(Debian 12, linux/amd64, running as the user openecraft, data in the volume
/data, licenses in /usr/share/doc/openecraft/):
| Image | Port | Tags |
|---|---|---|
ghcr.io/nilres/openecraft-parts-server | 8090 | <version>, <major>.<minor>, latest (releases), edge (master), sha-<commit> |
ghcr.io/nilres/openecraft-project-server | 8091 | the same |
docker run -d --name parts -p 127.0.0.1:8090:8090 -e OPENECRAFT_TOKEN=<secret> -v parts:/data ghcr.io/nilres/openecraft-parts-server
docker run -d --name projects -p 127.0.0.1:8091:8091 -e OPENECRAFT_PROJECT_TOKEN=<secret> -v projects:/data ghcr.io/nilres/openecraft-project-server
The settings of each image are in /etc/openecraft/parts-server.toml and
project-server.toml (bind = "0.0.0.0:<port>", data in /data); mount your own
file there or add command line options after the image name
(… openecraft-parts-server --install-catalogs all). The first administrator comes
from the environment too: -e OPENECRAFT_ADMIN_USER=admin -e OPENECRAFT_ADMIN_PASSWORD=<password> (OPENECRAFT_PROJECT_ADMIN_USER /
OPENECRAFT_PROJECT_ADMIN_PASSWORD for the project server) creates the account, or
resets its password, at every start.
A bind mount instead of a volume must be writable by the user of the image (uid 1000,
or start the container with --user). installer/docker/compose.yaml starts both
servers with Docker Compose. The servers speak plain HTTP: keep them on 127.0.0.1
behind a TLS reverse proxy when other machines reach them
(project server). Building the images yourself:
docker build -f installer/docker/Dockerfile --target parts-server -t openecraft-parts-server .
docker build -f installer/docker/Dockerfile --target project-server -t openecraft-project-server .
CI builds both images on every push, starts them once and checks that they answer;
on master and for a release tag it pushes them to the GitHub Container Registry
(job docker), together with the image of the web editor (below).
Every image has a workflow that rebuilds it alone, without the rest of CI, started by hand under Actions (› Run workflow):
| Image | Workflow | Check |
|---|---|---|
openecraft-parts-server | Docker image of the parts server (docker-parts-server.yml) | check-server.sh parts |
openecraft-project-server | Docker image of the project server (docker-project-server.yml) | check-server.sh project |
openecraft-web | Docker image of the web editor (docker-web.yml) | check-editor-web.sh |
openecraft-website | Docker image of the website (docker-website.yml) | check-website.sh |
All four take the same inputs and share their steps (.github/workflows/docker-image.yml):
a branch, a release tag (v0.1.2, also one older than the workflow) or a commit to
build (ref), further tags (tags), whether to push (push) and whether to build
without the build cache (no-cache). The image is checked like in CI (the scripts of
installer/docker/) and pushed with the tags CI gives that commit (sha-<commit>,
edge for the tip of master, <version>, and <major>.<minor> and latest only
when no newer release has them), plus the tags given. From the command line:
gh workflow run docker-parts-server.yml -f ref=v0.1.2
gh workflow run docker-project-server.yml -f ref=master -f no-cache=true
gh workflow run docker-web.yml -f tags=test
gh workflow run docker-website.yml -f push=false
Web (WebAssembly)
The web version runs without installing at editor.openecraft.org; the project's website openecraft.org links to it. To host it yourself:
rustup target add wasm32-unknown-unknown
cargo install trunk@0.22.1 --locked
cd openecraft && trunk serve # development server on http://127.0.0.1:8080
cd openecraft && trunk build --release # static files in openecraft/dist/ – host them on any web server
Both web builds put LICENSE-MIT, LICENSE-APACHE and OFL-NotoSans.txt next to the
page, the release build also THIRD-PARTY-LICENSES.html (installer/web/licenses.sh,
on Windows licenses.ps1, run by trunk after the build); keep these files when hosting
the page.
In the browser "Save" downloads the project file and "Open" uses the file picker.
Legal notice of a web editor
Help › Legal and privacy of the editor shows the disclaimer of OpenECraft (no
warranty, the product names it mentions belong to their owners) and its privacy notice:
what the editor stores and where, and which servers it talks to. A web editor that is
hosted for others also shows who runs it, as many countries require (in Germany the
Impressum of § 5 DDG), and what the operator adds to the privacy notice (the hosting,
the logs of the web server, whom to ask). Both are set in legal of config.js beside
the page (openecraft/config.js, copied by the build; edit it after a build) with the
fields of the website: name (empty: no legal notice),
address, email, phone, representative, register, vat, responsible, text
and privacy; lines of the address and the texts are separated by \n or |. The
web editor the website brings along at /editor/ shows the notice of the website. The
desktop editor has no operator and shows the disclaimer and the privacy notice alone.
The parts manager has the same texts behind Legal and privacy of its top bar, with a
privacy notice of its own; its web build takes the same config.js.
Keep the texts true: a change of the editor that stores or sends something else
changes them too (crates/openecraft-ui/src/legal.rs).
Docker image of the web editor
ghcr.io/nilres/openecraft-web (same tags as the server images) serves the release
build of the web editor with nginx on port 8080, as an unprivileged user, with the
license files next to the page; installer/docker/compose.yaml starts it with the
servers. The servers are reached from the browser, not from the container: in the
editor give them with the address the browser uses (http://127.0.0.1:8090 with the
compose file); both servers allow requests from every origin.
docker run -d --name openecraft-web -p 127.0.0.1:8080:8080 ghcr.io/nilres/openecraft-web
docker build -f installer/docker/Dockerfile --target editor-web -t openecraft-web .
Who runs the editor is set with the variables OPENECRAFT_LEGAL_NAME,
OPENECRAFT_LEGAL_ADDRESS, OPENECRAFT_LEGAL_EMAIL, OPENECRAFT_LEGAL_PHONE,
OPENECRAFT_LEGAL_REPRESENTATIVE, OPENECRAFT_LEGAL_REGISTER, OPENECRAFT_LEGAL_VAT_ID,
OPENECRAFT_LEGAL_RESPONSIBLE, OPENECRAFT_LEGAL_TEXT and OPENECRAFT_LEGAL_PRIVACY
(below, Legal notice of a web editor): the image writes
config.js from them at every start.
The nginx site is installer/docker/editor-web.conf (mount your own at
/etc/nginx/conf.d/default.conf): index.html and the other files are checked at
every visit, the WebAssembly and its script, named after their hash, are cached for a
year. The WebAssembly is 32 MB (a release build of the page is optimised for size: the
profile web of the root Cargo.toml, which takes about a quarter of an hour); the
build of the image compresses it once
(installer/docker/compress.sh) and nginx sends the copy as it is: 8 MB with Brotli
to browsers that ask for it, which they do over HTTPS only, 12 MB with gzip otherwise.
A server of your own should send such copies as well instead of compressing the file
for every visitor. Put a TLS reverse
proxy in front of it for other machines, as for the servers. Beside the page are
worker.js, a worker that searches the 3D routing of an opened project so the page
stays responsive meanwhile, routing/, the routings of the examples from the
build, so that an example opens at once, and i18n/, the texts of the languages
other than English, German, French and Spanish (<code>.tsv): the page fetches the
file of a language when it is used instead of carrying all of them, and shows the
language in English if the file is missing. While the WebAssembly is loaded the page
shows the progress (loading.js).
The workflow Docker image of the web editor (.github/workflows/docker-web.yml)
rebuilds this image alone, without the rest of CI
(above).
Website
The website of the project with its live demos, openecraft.org,
is a web build of its own (website/),
deployed by hand as static files or with the Docker image
ghcr.io/nilres/openecraft-website, which brings the web editor along at /editor/:
see website.md.
Tests
cargo test --workspace
cargo clippy --workspace --all-targets
cargo clippy -p openecraft -p openecraft-parts-manager -p openecraft-website --target wasm32-unknown-unknown
All three must pass without warnings (CI runs them with -D warnings).