Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HelenaLM32/ECHO/llms.txt

Use this file to discover all available pages before exploring further.

ECHO ships as a Docker Compose project with three core services: a MariaDB database, a Spring Boot backend, and a React frontend. A fourth optional service (admin-init) bootstraps the initial administrator account and only runs when you explicitly invoke it.
1

Clone the repository

git clone https://github.com/HelenaLM32/ECHO.git
cd ECHO
2

Configure environment variables

Copy the example environment file and fill in the required values:
cp .env.example .env
Open .env in your editor and set the following variables. Required values are marked in the table below.
VariableDescriptionRequired
MYSQL_ROOT_PASSWORDRoot password for the MariaDB instanceYes
MYSQL_DATABASEName of the database created on startupYes
MYSQL_USERApplication database userYes
MYSQL_PASSWORDPassword for the application database userYes
BACKEND_PORTHost port the backend binds to (default: 8084)Yes
ECHO_JWT_SECRETSecret used to sign JWT tokens — must be 32+ charactersYes
CORS_ALLOWED_ORIGINFrontend origin the backend allows CORS fromYes
APP_UPLOAD_DIRPath inside the container where uploads are storedYes
FRONTEND_PORTHost port the frontend binds to (default: 8083)Yes
VITE_API_URLAPI prefix used by the frontend (default: /api)Yes
TRAEFIK_HOSTHost IP or domain for reverse proxy routingNo
APP_ADMIN_EMAILEmail for the bootstrap admin accountNo
APP_ADMIN_USERNAMEUsername for the bootstrap admin accountNo
APP_ADMIN_PASSWORDPlain-text password for the admin (used by admin-init)No
APP_ADMIN_PASSWORD_HASHBcrypt hash of the admin passwordNo
GOOGLE_CLIENT_IDGoogle OAuth2 client IDNo
GOOGLE_CLIENT_SECRETGoogle OAuth2 client secretNo
Set ECHO_JWT_SECRET to a random string of at least 32 characters. Any value shorter than 32 characters will be rejected at startup. Never commit this value to version control.
Set CORS_ALLOWED_ORIGIN to the exact origin of your frontend — including the protocol and port (e.g., http://localhost:8083 for local development, or your production domain). An incorrect value will block all API requests from the browser.
Uploaded files (images, attachments) are stored at ./uploads on the host, mounted into the backend container at APP_UPLOAD_DIR. This directory persists between container restarts. Back it up separately if you need to preserve user-uploaded content.
3

Build and start the services

docker compose up -d --build
Docker Compose builds the backend and frontend images, pulls MariaDB, and starts all three services in detached mode. On first run, the database is initialized automatically using the MYSQL_* variables from your .env file.Verify all containers are running:
docker compose ps
You should see db, backend, and frontend all in the running state.
4

Bootstrap the admin account (optional)

The admin-init service creates the first administrator account. It runs once and exits — it does not stay running.Before running it, set the following variables in your .env:
  • APP_ADMIN_EMAIL — the admin’s email address
  • APP_ADMIN_USERNAME — the admin’s username
  • APP_ADMIN_PASSWORD_HASH — a bcrypt hash of the desired password
Then run the service:
docker compose --profile tools run --rm admin-init
Generate a bcrypt hash from the command line with:
htpasswd -bnBC 10 "" your_password | tr -d ':\n'
Or use any online bcrypt generator. Store only the hash in .env, never the plain-text password.
5

Access the application

Once all services are running:
ServiceURL
Frontendhttp://localhost:8083
Backend APIhttp://localhost:8084
Change the port numbers if you modified FRONTEND_PORT or BACKEND_PORT in your .env.

​
Stopping and removing containers

Stop all running services: 
docker compose down
Stop and remove the database volume (this deletes all data): 
docker compose down -v
Running docker compose down -v permanently deletes the MariaDB data volume. All database content will be lost. Only use this if you want a clean slate or are decommissioning the instance.

​
Service overview

The Docker Compose project defines the following services:
ServiceImageDescription
dbMariaDBRelational database. Data persisted in a named volume.
backendSpring Boot (Java)REST API server. Mapped from internal port 8082 to host BACKEND_PORT.
frontendReact (Vite, Nginx)Web UI. Mapped from internal port 80 to host FRONTEND_PORT.
admin-initSpring Boot taskOne-shot service that creates the admin account. Only runs with --profile tools.

Build docs developers (and LLMs) love

Get started for freeTalk to us