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 https://github.com/edge-mining/app.git
cd app/

Repository layout:

• core/: Edge Mining backend and domain logic
• frontend/: Vue web UI
• root files: Docker Compose, Nginx, application scripts, release metadata

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 port 80

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

Under the hood this will:

• Run init_user_data.sh to create/populate the user_data/ directory
• Run docker compose up -d --build to build the multi-stage image defined in Dockerfile (backend + frontend + nginx) and start a single container exposing the web UI and API on port 80

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 down

Volumes 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: 5 seconds)

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=5

When 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

Once the container is running in the background with:

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 interactive

This command:

• enters the edge-mining service container defined in compose.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 --help

User-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 from core/data/policies/ on first run if missing)
• user_data/examples/ – example rules files (copied from core/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/ into user_data/policies/
• Copy example rules files from core/data/examples/ into user_data/examples/ if you want to use them as templates
• Let the backend create user_data/db/edgemining.db automatically, 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.sh

This 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.db file exists (copying one from core/ 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 -f to 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.sh if 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.

When a new version is available, use the update.sh script to pull the latest changes and restart the application:

./update.sh

This script will:

• Pull the latest changes from the current branch
• 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.sh

This script will:

• Fetch the latest remote branches
• Display a numbered list of all available branches
• Prompt you to select the desired branch
• Switch to the selected branch
• Rebuild and restart the Docker stack

After updating the backend or frontend code, update the VERSION.json file with the new application version before committing the release change. This file is served statically by Nginx and must stay aligned with the bundled application state.

Procedure:

1. Update the relevant files under core/ and/or frontend/.
2. Edit VERSION.json and enter the desired new version.
3. Commit the code and VERSION.json together.

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.