enuxia-frappe-aio/README.md

Enuxia Frappe AIO

Version française

A local, security-oriented controller for operating a Frappe or ERPNext stack.

Technical Preview — v0.1.0

The current release supports service monitoring, bounded logs, Frappe backups, backup history, and read-only integrity verification. Restore, retention, scheduling, packaging, and production hardening are still in progress.

Why this project exists

Operating a self-hosted Frappe stack often requires direct Docker access, shell commands, and knowledge of the deployment layout. Enuxia Frappe AIO introduces a safer operational layer:

• the web controller has no Docker socket access;
• the controller executes no system commands;
• privileged actions are exposed as typed, allow-listed agent operations;
• operations and results are persisted in SQLite;
• backups include a manifest and SHA-256 checksums;
• integrity verification runs read-only;
• service state and logs are obtained through the local agent.

Current capabilities

• Local Rust agent with Docker API access
• Unprivileged Axum/Askama controller
• Typed JSON protocol over a mode 0600 Unix socket
• Persistent operation queue and results in SQLite
• Complete Frappe backup workflow
• Four backup artifact roles: database, configuration, public files, private files
• Backup history
• Read-only integrity verification
• Size and SHA-256 verification for every artifact
• Typed status for the expected Frappe services
• Bounded service log retrieval
• Docker Compose discovery through labels
• Recovery of interrupted operations after agent restart

Architecture

Browser
  |
  v
enuxia-aio-controller
  - unprivileged
  - no Docker socket
  - no shell execution
  |
  | typed JSON / Unix socket
  v
enuxia-aio-agent
  - allow-listed operations
  - SQLite state
  - Docker API access
  |
  v
Frappe containers and temporary operation containers

See Architecture and Security model.

Project status

Capability	Status
Service status	Available
Bounded service logs	Available
Create backup	Available
Backup history	Available
Verify backup integrity	Available
Restore backup	Planned
Retention policy	Planned
Scheduled backups	Planned
Installation packaging	Planned
Production security audit	Not completed

Requirements

• Linux
• Rust stable toolchain
• Docker Engine
• A Docker Compose-managed Frappe stack
• A dedicated local Unix socket for controller-to-agent communication

The agent requires Docker access. Treat access to a Docker socket as highly privileged.

Development quick start

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace

Start the agent

export ENUXIA_AGENT_SOCKET="${XDG_RUNTIME_DIR}/enuxia-frappe-aio/agent.sock"
export ENUXIA_AGENT_STATE_DB="${XDG_STATE_HOME:-$HOME/.local/state}/enuxia-frappe-aio/agent.sqlite3"
export ENUXIA_DOCKER_HOST="unix:///var/run/docker.sock"
export ENUXIA_COMPOSE_PROJECT="my-frappe-project"
export ENUXIA_SITE_NAME="site.example.test"

cargo run -p enuxia-aio-agent

Start the controller

unset ENUXIA_DOCKER_HOST
unset DOCKER_HOST

export ENUXIA_AGENT_SOCKET="${XDG_RUNTIME_DIR}/enuxia-frappe-aio/agent.sock"
export ENUXIA_COMPOSE_PROJECT="my-frappe-project"
export ENUXIA_INSTANCE_NAME="my-frappe-instance"
export ENUXIA_SITE_NAME="site.example.test"
export ENUXIA_TARGET_NAME="local-node"

cargo run -p enuxia-aio-controller

Open http://127.0.0.1:3000.

Additional variables are documented in .env.example.

Expected Compose services

The current dashboard expects these Compose service labels:

• frontend
• backend
• db
• redis-cache
• redis-queue
• websocket
• queue-short
• queue-long
• scheduler

Physical container names are not part of the public contract.

Backup model

Each successful backup records a unique identifier, site, timestamp, total size, storage location, four artifacts, and one SHA-256 checksum per artifact.

Integrity verification reloads the persisted manifest, mounts backup storage read-only, recomputes sizes and checksums, and persists a structured verification result.

This is not a replacement for off-site backups, restore testing, or a disaster-recovery plan.

Security

Read SECURITY.md before reporting a vulnerability.

Important constraints:

• never expose the agent socket over TCP;
• never expose the Docker socket to the controller;
• never add arbitrary shell execution to the protocol;
• treat the agent as a privileged local component;
• do not use this technical preview as the only backup mechanism.

Contributing

Read CONTRIBUTING.md before opening a pull request.

Roadmap

See ROADMAP.md.

License

Apache License 2.0. See LICENSE.

Disclaimer

This is an independent open-source project by Enuxia. It is not affiliated with or endorsed by Frappe Technologies.