This repository bundles the Edge Mining core backend and web frontend into a single runnable application.
Edge Mining is intended to be run via Docker Compose.
- Git
- Docker and Docker Compose
Clone the repository and move into the project root:
git clone --recurse-submodules https://github.com/edge-mining/app.git
cd app/This setup runs a single container that bundles:
core: Edge Mining backend (FastAPI, automation engine)frontend: Vue web UI (served as static files)nginx: reverse proxy exposing everything on port80
On the very first run, use the first_start.sh helper script, which initializes user_data/ and then brings up the Docker stack, building the image if needed:
./first_start.shUnder the hood this will:
- Run
init_user_data.shto create/populate theuser_data/directory - Run
docker compose up -d --buildto build the multi-stage image defined inDockerfile(backend + frontend + nginx) and start a single container exposing the web UI and API on port80
After the first initialization, you can start the stack directly with Docker Compose (without forcing a rebuild every time):
docker compose up -d- Web UI:
http://localhost/ - API (via reverse proxy):
http://localhost/api - API docs (via reverse proxy):
http://localhost/docs
docker compose downVolumes under user_data/ are mounted into the container so that configuration and database files persist across restarts.
The container supports a couple of environment variables that control runtime behavior:
TIMEZONE: timezone used by the backend (default:Europe/Rome)SCHEDULER_INTERVAL_SECONDS: polling interval for the scheduler loop (default:5seconds)
When using Docker Compose, you can configure them in compose.yaml under the environment section of the edge-mining service. For example:
services:
edge-mining:
environment:
- TIMEZONE=Europe/Rome
- SCHEDULER_INTERVAL_SECONDS=5When running the image directly with docker run, you can pass them with -e:
docker run -d \
-p 80:80 \
-e TIMEZONE=Europe/Rome \
-e SCHEDULER_INTERVAL_SECONDS=5 \
edge-mining:latest### 2.6. Core interactive CLI mode
Once the container is running in the background with:
```bash
docker compose up -d
you can open an interactive Core CLI session inside the running container using docker compose exec and the startup command described in the core README:
docker compose exec edge-mining python -m edge_mining cli interactiveThis command:
- enters the
edge-miningservice container defined incompose.yaml - starts the backend in interactive CLI mode, allowing you to manage miners, energy sources, controllers, policies, etc. via a text-based menu.
To see the available CLI options you can run:
docker compose exec edge-mining python -m edge_mining cli --helpUser-specific data lives in the user_data/ folder of the this application folder. This is where you can place your own configuration files, policies, and where the backend will store its database.:
user_data/policies/– optimization policy YAML files (automatically copied fromcore/data/policies/on first run if missing)user_data/examples/– example rule 8000 s files (copied fromcore/data/examples/on first run)user_data/db/edgemining.db– SQLite database file used by the backend
On first run you can:
- Copy or adjust default policies from
core/data/policies/intouser_data/policies/ - Copy example rules files from
core/data/examples/intouser_data/examples/if you want to use them as templates - Let the backend create
user_data/db/edgemining.dbautomatically, or pre-populate it if you know what you are doing
The first_start.sh script already runs init_user_data.sh for you, so in normal usage you do not need to call it manually on the first run.
If you prefer to manage things yourself, you can still run the helper script directly to create and populate the user_data/ directory with default files:
./init_user_data.shThis script:
- Creates the
user_data/structure if missing - Copies example optimization policies into
user_data/policies/ - Copies example rules files into
user_data/examples/ - Ensures a
user_data/db/edgemining.dbfile exists (copying one fromcore/if present, or creating an empty file otherwise)
You may want to re-run it if you intentionally delete the user_data/ folder and want to restore the default structure.
- Logs: Use
docker compose logs -fto inspect services when running with Docker. - Rebuild after changes: If you change backend or frontend code, re-run
docker compose up -d --build(or./first_start.shif you prefer the one-shot helper) to rebuild images.
- If containers fail to start, check logs:
docker compose logs- If ports are already in use (80), stop the conflicting services or adjust ports and Nginx configuration.
- If the UI cannot reach the API, verify:
- Backend container is healthy (
docker ps) - Nginx is running and correctly proxying requests
- Frontend is pointing to the right API URL.
- Backend container is healthy (
When a new version is available, use the update.sh script to pull the latest changes (including submodules) and restart the application:
./update.shThis script will:
- Pull the latest changes from the current branch (with
--recurse-submodules) - Ensure all submodules are in sync
- Re-initialize
user_data/(copies missing defaults only) - Rebuild and restart the Docker stack
To switch to a different branch (e.g. from main to dev), use the switch_branch.sh script:
./switch_branch.shThis script will:
- Fetch the latest remote branches
- Display a numbered list of all available branches
- Prompt you to select the desired branch
- Switch with
--recurse-submodulesso that all submodules are correctly updated to the matching commit - Rebuild and restart the Docker stack
This repository uses Git submodules for the core and frontend components. The submodules are configured to track the dev and develop branches respectively.
After cloning, the submodules will be checked out at the commit SHAs recorded in the parent repository. To update them to the latest commits from their respective branches:
# Update all submodules to the latest commits from their configured branches
git submodule update --remote --mergeTo update a specific submodule:
# Update core submodule to latest dev branch
cd core
git checkout dev
git pull origin dev
cd ..
# Update frontend submodule to latest develop branch
cd frontend
git checkout develop
git pull origin develop
cd ..After updating the core and frontend submodules (see above), but before committing changes to the main app repository, you need to update the VERSION.json file with the new application version. This file is served statically by Nginx and must be updated whenever there is a change involving the backend or frontend.
Procedure:
- Update the
coreandfrontendsubmodules as described above. - Edit the
VERSION.jsonfile and enter the desired new version (for example, by incrementing the version number or adding a date/commit). - Only after updating
VERSION.json, commit the changes in theapprepository.
Example of an update:
# Edit VERSION.json (for example with nano or vim)
nano VERSION.json
# ... update the version ...
git add core frontend VERSION.json
git commit -m "Update core, frontend and VERSION.json"Note: It is important to keep VERSION.json aligned with the actual state of backend and frontend for correct traceability of the distributed version.
Note: After updating the submodules, if you want to commit the new submodule references in the main repository:
git add core frontend
git commit -m "Update submodules to latest dev/develop branches"