Documentation

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
PackageFileInstallBuild tool
Debian, Ubuntuopenecraft_<version>_amd64.debsudo apt install ./openecraft_*.debdpkg-dev
Fedora, RHEL, openSUSEopenecraft-<version>-1.x86_64.rpmsudo dnf install ./openecraft-*.rpmrpmbuild
Any distributionOpenECraft-<version>-x86_64.AppImagechmod +x, start itDebian or Ubuntu, patchelf, zsync, appimagetool and its runtime (downloaded, checksums verified)
Any distributionOpenECraft-<version>-x86_64.flatpakflatpak install --user OpenECraft-*.flatpakflatpak-builder
Any distributionopenecraft_<version>_amd64.snapsudo snap install --dangerous openecraft_*.snapsnapcraft
Any distributionOpenECraft-<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:

InstallationUpdate
Windows setupOpenECraft-<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
AppImagethe AppImage file is replaced at once; the new version starts next time (AppImageUpdate and similar tools update it too)
macOS appOpenECraft.app (and OpenECraft Parts Manager.app next to it) are replaced from the disk image at once
deb, rpm, Flatpak, Snap, tar.gz, own buildthe 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/):

ImagePortTags
ghcr.io/nilres/openecraft-parts-server8090<version>, <major>.<minor>, latest (releases), edge (master), sha-<commit>
ghcr.io/nilres/openecraft-project-server8091the 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):

ImageWorkflowCheck
openecraft-parts-serverDocker image of the parts server (docker-parts-server.yml)check-server.sh parts
openecraft-project-serverDocker image of the project server (docker-project-server.yml)check-server.sh project
openecraft-webDocker image of the web editor (docker-web.yml)check-editor-web.sh
openecraft-websiteDocker 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.

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).

This document in the repository

More documentation

Getting started: from the first page to the bill of materials

This tutorial walks through a small control circuit in OpenECraft: pages, symbols, wires, devices with parts, terminals, a PLC, the project check, reports, the panel layout and the output. Commands are written as Tab ›…

Read

User interface

The editor's layout and the commands and keys of everyday work. New users start with the tutorial.

Read

Schematic editor

Pages, devices and their structure, live cross references, editing tools, navigators and project storage. The user interface lists the commands and keys.

Read

Symbols and libraries

The built-in symbol libraries (IEC, NFPA / JIC, GB, GOST, JIS, fluid power, P&ID, single-line) and the symbol editor for own symbols.

Read

Wires, cables, potentials and numbering

How connections get their cable, colour, cross-section and number, and how devices, pages and wires are numbered.

Read

Terminal strips, plugs, PLC and marking

Terminal strips with multi-level terminals and accessories, plugs, PLC cards with the exchange to PLC programming tools, and the markers for the workshop.

Read

Macros, configurator and table editing

Reuse of circuits as macros with variants and placeholders, pages generated by the configurator, and bulk changes in tables and spreadsheets.

Read

Parts management

The parts database shared by all projects (EPLAN style): commercial, technical and mounting data, function templates, connection points, 2D / 3D graphics and the import of manufacturer data. Parts are shared between…

Read

Reports, forms and the project check

Reports as windows, CSV / Excel or live report pages, title blocks and report forms (also graphical and own drawn forms), and the project check with its message management.

Read

Electrical sizing, calculations and verification

Conductor sizing, short circuit and protection coordination, load calculation, EMC, functional safety and rule sets – all part of the project check – and the inspection and test report of the installation.

Read

Panel layout, rooms and 3D routing

OpenECraft aligns the device's clip to the rail centerline. For Beckhoff's 12 × 100 × 68 mm EL I/O housings with 8 or 16 terminals, and the matching EK1100 coupler, the rail center is 63.8 mm from the top. For example…

Read

Wiring and mounting assistants

The panel layout as a checklist for the workshop, on a desktop or a tablet.

Read

Fluid power, process and plant engineering

Hoses and pipes in their own nets, electro-fluid links, PCT loops, the pre-planning of the plant and single-line / multi-line engineering.

Read

Wire harnesses

Harnesses with 3D topology, protections and fixings, KBL export, the harness interface for machines and nailboard drawings (Connections › Harnesses…). The example project conveyor has a door harness.

Read

Output and data exchange

PDF, DXF / DWG, SVG and 3D exports, DXF / DWG import, the enterprise integration layer (ERP, PDM, PLM, ECAD, MCAD, procurement, wiring machines) and Autodesk Vault.

Read

Revisions, review and change management

Revisions with locked pages and marked changes, the approval workflow, baselines with compare and merge, comments and redlining, and change requests.

Read

Command line, MCP server and plugins

Projects and the parts server without a window, for scripts and AI agents.

Read

Plugins

OpenECraft is extended through the openecraft-api crate. A plugin adds

Read

Parts server and parts manager

The data portal shared by all OpenECraft installations and the app that maintains it.

Read

Project server

Shared projects for a team: several users work on the same project, each page is locked by one of them.

Read

Access control of the servers

The parts server and the project server share one access model: users sign in with a local account or with a directory (Active Directory, OpenLDAP or another LDAP server), and what they may do comes from roles given to…

Read