ERPNext BARE METAL
Installationsanleitung · Ubuntu Server
Installationsanleitung

ERPNext Bare Metal
auf Ubuntu Server

Manuelle Installation ohne Docker – mit MariaDB, Redis, Python, Node.js, Bench, Nginx und Supervisor.

Stand 16.09.2026 Ubuntu 26.04.1 LTS ERPNext / Frappe v16 Bare Metal
BrowserHTTPS · 443
NginxReverse Proxy · Static Files
Frappe WebGunicorn · Python
MariaDBERP-Daten
WorkersQueue · Scheduler
RedisCache · Queue
Socket.IONode.js
SupervisorProzessüberwachung
ZIEL DIESES SKRIPTS
Du installierst ERPNext v16 vollständig ohne Container. Dabei lernst du nicht nur die Befehle, sondern auch, welche Aufgabe MariaDB, Redis, Python, Node.js, Bench, Nginx und Supervisor übernehmen.
OFFIZIELLE WARNUNG
Frappe empfiehlt für neue Produktionsinstallationen Docker. Bare Metal ist besonders für Lernen, Labore und bewusst selbstverwaltete Umgebungen interessant.
01 · Architektur

Was Bare Metal hier bedeutet

Bei Docker liegen Anwendung und Abhängigkeiten in Containern. Bei Bare Metal installierst und pflegst du alle Komponenten direkt auf dem Ubuntu-Server.

KomponenteAufgabe
MariaDBSpeichert Geschäftsdaten, Benutzer, Belege und Konfiguration.
RedisCache und Warteschlangen für Hintergrundjobs und Echtzeitfunktionen.
Python 3.14Führt Frappe und die serverseitige ERPNext-Logik aus.
Node.js 24 + YarnBauen Frontend-Assets und unterstützen Echtzeitfunktionen.
BenchVerwaltet Apps, Sites, Updates, Backups und Produktionskonfiguration.
NginxReverse Proxy, statische Dateien und HTTPS.
SupervisorHält Webprozess, Worker, Scheduler und Redis-Prozesse am Laufen.
FISI-BEZUG
Bare Metal macht die einzelnen Schichten besonders sichtbar: Netzwerk → Reverse Proxy → Anwendung → Hintergrunddienste → Datenbank.
02 · Aktueller Stand

Welche Versionen Frappe v16 erwartet

Die aktuellen Frappe-Unterlagen nennen für v16/develop konkrete Zielversionen. Prüfe diese Werte nach der Installation.

AbhängigkeitFrappe v16Prüfbefehl
MariaDB11.8mariadb --version
Python3.14uv python list
Node.js24node -v
Redis / Valkey6+redis-server --version
Yarn1.22+yarn -v
wkhtmltopdf0.12.6 patched Qtwkhtmltopdf --version
UbuntuHostsystem
→
MariaDB + RedisDatenbank · Cache · Queue
→
Python + NodeBackend · Assets
→
BenchFrappe · ERPNext
WICHTIG
Wenn MariaDB nach der Paketinstallation deutlich älter als die von Frappe erwartete Version ist, nicht einfach fortfahren. Dann passende MariaDB-Paketquelle verwenden oder auf die empfohlene Docker-Variante wechseln.
03 · Voraussetzungen

Server, DNS und Ressourcen vorbereiten

BereichEmpfehlung
CPU2–4 vCPU
RAMMindestens 8 GB für eine komfortable Einzelserver-Installation
DatenträgerSSD, mindestens ca. 50 GB mit Reserve für Backups und Logs
DNSerp.firma.de zeigt auf die Server-IP
Netzwerk80/TCP und 443/TCP erreichbar; SSH-Verbindung gesichert

Vor Beginn festlegen

  • Site-Name: erp.firma.de
  • Linux-Servicebenutzer: frappe
  • Bench-Pfad: /home/frappe/frappe-bench
  • ERPNext-Zweig: version-16
  • Starkes MariaDB-root-Passwort und separates ERPNext-Administratorpasswort
04 · Ubuntu vorbereiten

System aktualisieren und Basiswerkzeuge installieren

1
System aktualisieren
sudo apt update
sudo apt full-upgrade -y
2
Grundwerkzeuge installieren
sudo apt install -y git curl wget ca-certificates build-essential \
  pkg-config libffi-dev libssl-dev
3
Zeitzone setzen
sudo timedatectl set-timezone Europe/Berlin
timedatectl
4
Optional neu starten
sudo reboot
05 · Datenbank und Redis

MariaDB und Redis installieren

sudo apt install -y git redis-server libmariadb-dev \
  mariadb-server mariadb-client pkg-config

Dienste aktivieren und prüfen

sudo systemctl enable --now mariadb redis-server

mariadb --version
redis-server --version
systemctl --no-pager --full status mariadb
systemctl --no-pager --full status redis-server
VERSIONSPRÜFUNG
Für Frappe v16 nennt die aktuelle Dokumentation MariaDB 11.8 und Redis/Valkey 6+. Das Ergebnis von mariadb --version prüfen, bevor du weitermachst.
06 · MariaDB absichern

Root-Zugang und Zeichensatz vorbereiten

sudo mariadb-secure-installation

UTF-8-Konfiguration kontrollieren

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
sudo systemctl restart mariadb
sudo mariadb -e "SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server';"
07 · PDF-Engine

wkhtmltopdf mit patched Qt installieren

ERPNext verwendet wkhtmltopdf für bestimmte PDF-Ausgaben. Frappe nennt weiterhin Version 0.12.6 mit gepatchtem Qt.

sudo apt install -y xvfb libfontconfig
ACHTUNG
Bei sehr neuen Ubuntu-Versionen kann wkhtmltopdf der empfindlichste Bare-Metal-Baustein sein. Das passende 0.12.6-Paket für Architektur und Distribution von der offiziellen Downloadseite verwenden.
08 · Servicebenutzer

Eigenen Benutzer für Frappe anlegen

sudo adduser frappe
sudo usermod -aG sudo frappe
sudo -iu frappe
AB JETZT
Node.js, Python, Bench und ERPNext werden als Benutzer frappe installiert. Damit landen nvm, uv und die Bench-Dateien im Home-Verzeichnis dieses Benutzers.
09 · Node.js und Yarn

Node.js 24 per nvm installieren

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc

nvm install 24
nvm alias default 24
node -v
npm -v

npm install -g yarn
yarn -v
10 · Python und Bench

Python 3.14 und Bench CLI installieren

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

uv python install 3.14 --default
uv python list

uv tool install frappe-bench
bench --version
MERKSATZ
Bench ist nicht ERPNext. Bench ist das Verwaltungswerkzeug, das Frappe, ERPNext, Sites, Updates, Backups und Produktionskonfiguration steuert.
11 · Frappe-Bench

Bench für Frappe v16 initialisieren

cd ~
bench init --frappe-branch version-16 frappe-bench
cd ~/frappe-bench
PfadBedeutung
apps/Frappe und später ERPNext als Git-Repositories.
env/Python-Umgebung der Bench.
sites/Sites, Konfigurationen und öffentliche/private Dateien.
config/Redis-, Nginx- und Supervisor-Konfigurationen.
logs/Logs von Webprozess, Workern, Scheduler und Bench.
12 · ERPNext-App

ERPNext v16 zur Bench hinzufügen

cd ~/frappe-bench
bench get-app --branch version-16 erpnext https://github.com/frappe/erpnext
bench version
13 · Site erstellen

Datenbank und ERPNext-Site anlegen

cd ~/frappe-bench
bench new-site erp.firma.de
bench --site erp.firma.de install-app erpnext
bench use erp.firma.de
bench --site erp.firma.de list-apps
PASSWÖRTER
Beim Anlegen der Site wird das MariaDB-root-Passwort benötigt. Das ERPNext-Administratorpasswort ist später das Login-Passwort für den Benutzer Administrator.
14 · Funktionstest

Vor Nginx erst lokal testen

cd ~/frappe-bench
bench start

In einem zweiten Terminal

curl -I -H 'Host: erp.firma.de' http://127.0.0.1:8000
NICHT PRODUKTIV
bench start ist Entwicklungsmodus. Für den Dauerbetrieb werden Supervisor und Nginx eingerichtet.
15 · Produktionsdienste

Nginx und Supervisor installieren

sudo apt install -y nginx supervisor fail2ban
sudo systemctl enable --now nginx supervisor
16 · Supervisor

Frappe-Prozesse dauerhaft betreiben

cd ~/frappe-bench
bench setup supervisor

sudo ln -s /home/frappe/frappe-bench/config/supervisor.conf \
  /etc/supervisor/conf.d/frappe-bench.conf

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
17 · Nginx

Reverse Proxy und statische Dateien einrichten

cd ~/frappe-bench
bench config dns_multitenant on
bench setup nginx

sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -s /home/frappe/frappe-bench/config/nginx.conf \
  /etc/nginx/conf.d/frappe-bench.conf

sudo nginx -t
sudo systemctl reload nginx
18 · Scheduler und Hintergrundjobs

Zeitgesteuerte Aufgaben einschalten

cd ~/frappe-bench
bench --site erp.firma.de enable-scheduler
bench doctor
  • E-Mail-Warteschlangen
  • periodische ERPNext-Aufgaben
  • geplante Berichte und Benachrichtigungen
  • Backups und Wartungsjobs
  • lange oder zeitversetzte Queue-Jobs
19 · DNS und Firewall

Server erreichbar machen, ohne alles zu öffnen

PortZweckÖffentlich?
22/TCPSSHnur wenn benötigt
80/TCPHTTP / Let's Encryptja
443/TCPHTTPSja
3306/TCPMariaDBnein
RedisCache / Queuenein
 
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

getent ahosts erp.firma.de
20 · HTTPS

Let's Encrypt über Bench einrichten

cd ~/frappe-bench
sudo -H bench setup lets-encrypt erp.firma.de

Falls sudo bench nicht findet

cd ~/frappe-bench
sudo -H $(command -v bench) setup lets-encrypt erp.firma.de
sudo nginx -t
sudo systemctl reload nginx
curl -I https://erp.firma.de
21 · Erster Login

ERPNext im Browser öffnen

https://erp.firma.de
FeldWert
BenutzerAdministrator
PasswortDas bei bench new-site vergebene Administratorpasswort
22 · Betrieb

Status und wichtige Dienste prüfen

sudo supervisorctl status
sudo systemctl status nginx --no-pager
sudo systemctl status mariadb --no-pager
sudo nginx -t

cd ~/frappe-bench
bench doctor
bench version

Nach Änderungen

cd ~/frappe-bench
bench restart
sudo nginx -t && sudo systemctl reload nginx
23 · Backups

Datenbank und Dateien sichern

cd ~/frappe-bench
bench --site erp.firma.de backup --with-files --compress

Backup-Verzeichnis

ls -lh ~/frappe-bench/sites/erp.firma.de/private/backups/

Backup-Zeitplan über Bench

bench setup backups
3-2-1-PRINZIP
Produktive Sicherungen nicht nur auf demselben Server belassen. Zusätzliche Kopien auf einem getrennten System halten und Wiederherstellungen testen.
24 · Updates

ERPNext und Frappe aktualisieren

cd ~/frappe-bench
bench --site erp.firma.de backup --with-files --compress
bench version
bench update
bench version
sudo supervisorctl status
sudo nginx -t
BRANCH BEACHTEN
Frappe und ERPNext sind auf version-16 gepinnt. Ein Hauptversionswechsel ist keine normale Kleinaktualisierung und sollte separat geplant werden.
25 · Fehlersuche

Typische Bare-Metal-Probleme

SymptomPrüfenHäufige Ursache
bench nicht gefundenecho $PATH, uv tool list~/.local/bin noch nicht im PATH
new-site scheitertMariaDB-Version, Root-Zugang, LogsDB-Version oder Authentifizierung
502 Bad Gatewaysupervisorctl statusFrappe-Webprozess läuft nicht
Nginx startet nichtsudo nginx -tDefault-Site oder doppelter Serverblock
404 / falsche SiteDNS, Hostname, dns_multitenantHost-Header passt nicht zum Site-Namen
PDF fehlerhaftwkhtmltopdf --versionfalsche oder ungepatchte wkhtmltopdf-Version
Jobs bleiben liegenbench doctor, SupervisorScheduler/Worker nicht aktiv

Logs

ls -lh ~/frappe-bench/logs/
tail -n 100 ~/frappe-bench/logs/web.error.log
tail -n 100 ~/frappe-bench/logs/worker.error.log
sudo journalctl -u nginx -n 100 --no-pager
sudo journalctl -u mariadb -n 100 --no-pager
26 · Schnellübersicht

Die Bare-Metal-Installation auf einen Blick

1
Systempakete: Ubuntu aktualisieren, MariaDB, Redis und Build-Werkzeuge installieren.
2
DB absichern: mariadb-secure-installation, Version und utf8mb4 prüfen.
3
Laufzeiten: nvm → Node 24; Yarn; uv → Python 3.14.
4
Bench: uv tool install frappe-bench.
5
Frappe: bench init --frappe-branch version-16 frappe-bench.
6
ERPNext: bench get-app --branch version-16 erpnext.
7
Site: bench new-site erp.firma.de.
8
App: bench --site erp.firma.de install-app erpnext.
9
Produktion: Supervisor und Nginx konfigurieren.
10
HTTPS: Let's Encrypt über Bench einrichten.
27 · Quellen und Stand

Grundlage der Anleitung

Die Anleitung basiert auf dem zuvor erstellten Bare-Metal-Lernskript. Für die dort enthaltenen Versions- und Installationsangaben wurden die offiziellen Frappe-, ERPNext- und Ubuntu-Unterlagen herangezogen.