{"id":28591567,"url":"https://github.com/monarc-project/monarcappfo","last_synced_at":"2026-04-01T17:02:23.644Z","repository":{"id":37458414,"uuid":"68016521","full_name":"monarc-project/MonarcAppFO","owner":"monarc-project","description":"MONARC - Method for an Optimised aNAlysis of Risks by @NC3-LU","archived":false,"fork":false,"pushed_at":"2026-03-27T15:15:43.000Z","size":84135,"stargazers_count":119,"open_issues_count":51,"forks_count":43,"subscribers_count":13,"default_branch":"master","last_synced_at":"2026-03-27T23:42:23.282Z","etag":null,"topics":["cases","cybersecurity","governance","monarc","risk-analysis","risk-assessment","risk-evaluation","risk-treatment","security","threat","vulnerabilities"],"latest_commit_sha":null,"homepage":"https://www.monarc.lu","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monarc-project.png","metadata":{"files":{"readme":"README.docker.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-09-12T14:27:42.000Z","updated_at":"2026-03-27T15:14:02.000Z","dependencies_parsed_at":"2023-10-20T21:53:12.721Z","dependency_job_id":"083c0a12-783d-4b84-a63f-a6c38ca5534b","html_url":"https://github.com/monarc-project/MonarcAppFO","commit_stats":null,"previous_names":[],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/monarc-project/MonarcAppFO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monarc-project%2FMonarcAppFO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monarc-project%2FMonarcAppFO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monarc-project%2FMonarcAppFO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monarc-project%2FMonarcAppFO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monarc-project","download_url":"https://codeload.github.com/monarc-project/MonarcAppFO/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monarc-project%2FMonarcAppFO/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cases","cybersecurity","governance","monarc","risk-analysis","risk-assessment","risk-evaluation","risk-treatment","security","threat","vulnerabilities"],"created_at":"2025-06-11T09:36:13.221Z","updated_at":"2026-04-01T17:02:23.621Z","avatar_url":"https://github.com/monarc-project.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Development Environment for MONARC FrontOffice\n\nThis guide explains how to set up a local development environment for MONARC FrontOffice using Docker.\n\n## Prerequisites\n\n- Docker Engine 20.10 or later\n- Docker Compose V2 (comes with Docker Desktop)\n- At least 8GB of RAM available for Docker\n- At least 20GB of free disk space\n\n## Quick Start\n\n### Option 1: Using the Makefile (Recommended)\n\n1. **Clone the repository** (if you haven't already):\n   ```bash\n   git clone https://github.com/monarc-project/MonarcAppFO\n   cd MonarcAppFO\n   ```\n\n2. **Start the development environment**:\n   ```bash\n   make start\n   ```\n   \n   This will automatically:\n   - Create `.env` file from `.env.dev` if it doesn't exist\n   - Build and start all services\n   - Display access URLs\n   \n   The first run will take several minutes as it:\n   - Builds the Docker images\n   - Installs all dependencies (PHP, Node.js, Python)\n   - Clones frontend repositories\n   - Initializes databases\n   - Sets up the stats service\n   - Creates the initial admin user\n\n3. **Access the application**:\n   - MONARC FrontOffice: http://localhost:5001\n   - Stats Service: http://localhost:5005\n   - MailCatcher (email testing): http://localhost:1080\n\n4. **Login credentials**:\n   - Username: `admin@admin.localhost`\n   - Password: `admin`\n\n### Option 2: Using Docker Compose Directly\n\n1. **Clone the repository** (if you haven't already):\n   ```bash\n   git clone https://github.com/monarc-project/MonarcAppFO\n   cd MonarcAppFO\n   ```\n\n2. **Copy the environment file**:\n   ```bash\n   cp .env.dev .env\n   ```\n\n3. **Customize environment variables** (optional):\n   Edit `.env` file to change default passwords and configuration:\n   ```bash\n   # Generate a secure secret key for stats service\n   openssl rand -hex 32\n   # Update STATS_SECRET_KEY in .env with the generated value\n   ```\n\n4. **Start the development environment**:\n   ```bash\n   docker compose -f docker-compose.dev.yml up --build\n   ```\n\n5. **Access the application**:\n   - MONARC FrontOffice: http://localhost:5001\n   - Stats Service: http://localhost:5005\n   - MailCatcher (email testing): http://localhost:1080\n\n6. **(Optional) Configure Stats API Key**:\n   The stats service generates an API key on first run. To retrieve it:\n   ```bash\n   # Using Makefile\n   make stats-key\n   \n   # Or manually check logs\n   docker compose -f docker-compose.dev.yml logs stats-service | grep \"Token:\"\n   \n   # Or create a new client and get the key\n   docker exec -it monarc-fo-stats poetry run flask client_create --name monarc\n   \n   # Update the .env file with the API key and restart the monarc service\n   docker compose -f docker-compose.dev.yml restart monarc\n   ```\n\n7. **Login credentials**:\n   - Username: `admin@admin.localhost`\n   - Password: `admin`\n\n## Services\n\nThe development environment includes the following services:\n\n| Service | Description | Port | Container Name |\n|---------|-------------|------|----------------|\n| monarc | Main FrontOffice application (PHP/Apache) | 5001 | monarc-fo-app |\n| db | MariaDB database | 3307 | monarc-fo-db |\n| postgres | PostgreSQL database (for stats) | 5432 | monarc-fo-postgres |\n| stats-service | MONARC Statistics Service | 5005 | monarc-fo-stats |\n| mailcatcher | Email testing tool | 1080 (web), 1025 (SMTP) | monarc-fo-mailcatcher |\n\n## Development Workflow\n\n### Makefile Commands\n\nThe Makefile provides convenient commands for managing the development environment.\nUse `ENV=\u003cname\u003e` to select `docker compose.\u003cname\u003e.yml` (default: `dev`).\n\n```bash\nmake start         # Start all services\nmake stop          # Stop all services\nmake restart       # Restart all services\nmake logs          # View logs from all services\nmake logs-app      # View logs from MONARC application\nmake logs-stats    # View logs from stats service\nmake shell         # Open a shell in the MONARC container\nmake shell-stats   # Open a shell in the stats service container\nmake db            # Open MySQL client\nmake status        # Show status of all services\nmake stats-key     # Show the stats API key\nmake reset         # Reset everything (removes all data)\n```\n\n### Live Code Editing\n\nThe application source code is mounted as a volume, so changes you make on your host machine will be immediately reflected in the container. After making changes:\n\n1. **PHP/Backend changes**: Apache automatically reloads modified files\n2. **Frontend changes**: You may need to rebuild the frontend:\n   ```bash\n   docker exec -it monarc-fo-app bash\n   cd /var/www/html/monarc\n   ./scripts/update-all.sh -d\n   ```\n\n### Accessing the Container\n\nUsing Makefile:\n```bash\nmake shell        # MONARC application\nmake shell-stats  # Stats service\n```\n\nOr directly with docker:\n```bash\ndocker exec -it monarc-fo-app bash      # MONARC application\ndocker exec -it monarc-fo-stats bash    # Stats service\n```\n\n### Database Access\n\nUsing Makefile:\n```bash\nmake db  # Connect to MariaDB\n```\n\nOr directly with docker:\n```bash\n# Connect to MariaDB\ndocker exec -it monarc-fo-db mysql -usqlmonarcuser -psqlmonarcuser monarc_common\n\n# Connect to PostgreSQL\ndocker exec -it monarc-fo-postgres psql -U sqlmonarcuser -d statsservice\n```\n\n### Viewing Logs\n\nUsing Makefile:\n```bash\nmake logs          # All services\nmake logs-app      # MONARC application only\nmake logs-stats    # Stats service only\n```\n\nOr directly with docker compose:\n```bash\n# View logs for all services\ndocker compose -f docker-compose.dev.yml logs -f\n\n# View logs for a specific service\ndocker compose -f docker-compose.dev.yml logs -f monarc\ndocker compose -f docker-compose.dev.yml logs -f stats-service\n```\n\n### Restarting Services\n\nUsing Makefile:\n```bash\nmake restart  # Restart all services\n```\n\nOr directly with docker compose:\n```bash\n# Restart all services\ndocker compose -f docker-compose.dev.yml restart\n\n# Restart a specific service\ndocker compose -f docker-compose.dev.yml restart monarc\n```\n\n### Stopping the Environment\n\nUsing Makefile:\n```bash\nmake stop   # Stop all services (keeps data)\nmake reset  # Stop and remove everything including data\n```\n\nOr directly with docker compose:\n```bash\n# Stop all services (keeps data)\ndocker compose -f docker-compose.dev.yml stop\n\n# Stop and remove containers (keeps volumes/data)\ndocker compose -f docker-compose.dev.yml down\n\n# Stop and remove everything including data\ndocker compose -f docker-compose.dev.yml down -v\n```\n\n## Common Tasks\n\n### Using BackOffice monarc_common\n\nTo reuse the BackOffice `monarc_common` database:\n\n1. Set `USE_BO_COMMON=1` in `.env`.\n2. Point `DBHOST` to the BackOffice MariaDB host (for example, `monarc-bo-db` on a shared Docker network).\n3. Ensure the BackOffice database already has `monarc_common` and grants for `DBUSER_MONARC`.\n\n### Shared Docker Network\n\nTo connect FrontOffice and BackOffice containers, use a shared external network:\n\n1. Create the network once: `docker network create monarc-network`\n2. Set `MONARC_NETWORK_NAME=monarc-network` in both projects' `.env` files.\n3. Ensure the BackOffice compose file also uses the same external network name.\n\n### Resetting the Database\n\nTo completely reset the databases:\n```bash\ndocker compose -f docker-compose.dev.yml down -v\ndocker compose -f docker-compose.dev.yml up --build\n```\n\n### Installing New PHP Dependencies\n\n```bash\ndocker exec -it monarc-fo-app bash\ncomposer require package/name\n```\n\n### Installing New Node Dependencies\n\n```bash\ndocker exec -it monarc-fo-app bash\ncd node_modules/ng_client  # or ng_anr\nnpm install package-name\n```\n\n### Running Database Migrations\n\n```bash\ndocker exec -it monarc-fo-app bash\nphp ./vendor/robmorgan/phinx/bin/phinx migrate -c ./module/Monarc/FrontOffice/migrations/phinx.php\n```\n\n### Creating Database Seeds\n\n```bash\ndocker exec -it monarc-fo-app bash\nphp ./vendor/robmorgan/phinx/bin/phinx seed:run -c ./module/Monarc/FrontOffice/migrations/phinx.php\n```\n\n### Rebuilding Frontend\n\n```bash\ndocker exec -it monarc-fo-app bash\ncd /var/www/html/monarc\n./scripts/update-all.sh -d\n```\n\n## Debugging\n\n### Xdebug Configuration\n\nXdebug is enabled by default in the development image. To disable it, set\n`XDEBUG_ENABLED=0` in `.env` and rebuild the image (for example, `make start`).\nYou can also tune the connection behavior via `.env`:\n`XDEBUG_START_WITH_REQUEST`, `XDEBUG_CLIENT_HOST`, and `XDEBUG_CLIENT_PORT`.\n\nWhen enabled, Xdebug is pre-configured. To use it:\n\n1. Configure your IDE to listen on port 9003\n2. Set the IDE key to `IDEKEY`\n3. Start debugging in your IDE\n4. Trigger a request to the application\n\nFor PhpStorm:\n- Go to Settings → PHP → Debug\n- Set Xdebug port to 9003\n- Enable \"Can accept external connections\"\n- Set the path mappings: `/var/www/html/monarc` → your local project path\n\n### Checking Service Health\n\n```bash\n# Check if all services are running\ndocker compose -f docker-compose.dev.yml ps\n\n# Check specific service health\ndocker compose -f docker-compose.dev.yml ps monarc\n```\n\n## Troubleshooting\n\n### Port Conflicts\n\nIf you get port conflicts, you can change the ports in the `docker-compose.dev.yml` file:\n```yaml\nports:\n  - \"5001:80\"  # Change 5001 to another available port\n```\n\nTo change the MariaDB host port without editing the compose file, set\n`DBPORT_HOST` in `.env` (default: `3307`).\n\n### Permission Issues\n\nIf you encounter permission issues with mounted volumes:\n```bash\ndocker exec -it monarc-fo-app bash\nchown -R www-data:www-data /var/www/html/monarc/data\nchmod -R 775 /var/www/html/monarc/data\n```\n\n### Database Connection Issues\n\nCheck if the database is healthy:\n```bash\ndocker compose -f docker-compose.dev.yml ps db\n```\n\nIf needed, restart the database:\n```bash\ndocker compose -f docker-compose.dev.yml restart db\n```\n\n### Stats Service Issues\n\nCheck stats service logs:\n```bash\ndocker compose -f docker-compose.dev.yml logs stats-service\n```\n\nRestart the stats service:\n```bash\ndocker compose -f docker-compose.dev.yml restart stats-service\n```\n\n### Rebuilding from Scratch\n\nIf something goes wrong and you want to start fresh:\n```bash\n# Stop everything\ndocker compose -f docker-compose.dev.yml down -v\n\n# Remove all related containers, images, and volumes\ndocker system prune -a\n\n# Rebuild and start\ndocker compose -f docker-compose.dev.yml up --build\n```\n\n## Performance Optimization\n\nFor better performance on macOS and Windows:\n\n1. **Use Docker volume mounts for dependencies**: The compose file already uses named volumes for `vendor` and `node_modules` to improve performance.\n\n2. **Allocate more resources**: In Docker Desktop settings, increase:\n   - CPUs: 4 or more\n   - Memory: 8GB or more\n   - Swap: 2GB or more\n\n3. **Enable caching**: The Dockerfile uses apt cache and composer optimizations.\n\n## Comparison with Vagrant\n\n| Feature | Docker | Vagrant |\n|---------|--------|---------|\n| Startup time | Fast (~2-3 min) | Slow (~10-15 min) |\n| Resource usage | Lower | Higher |\n| Isolation | Container-level | VM-level |\n| Portability | Excellent | Good |\n| Live code reload | Yes | Yes |\n| Learning curve | Moderate | Low |\n\n## Environment Variables Reference\n\nAll environment variables are defined in the `.env` file:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `DBHOST` | MariaDB host for MONARC | `db` |\n| `DBPORT_HOST` | MariaDB host port (published) | `3307` |\n| `DBPASSWORD_ADMIN` | MariaDB root password | `root` |\n| `DBNAME_COMMON` | Common database name | `monarc_common` |\n| `DBNAME_CLI` | CLI database name | `monarc_cli` |\n| `DBUSER_MONARC` | Database user | `sqlmonarcuser` |\n| `DBPASSWORD_MONARC` | Database password | `sqlmonarcuser` |\n| `USE_BO_COMMON` | Use BackOffice `monarc_common` (`1/0`, `true/false`, `yes/no`) | `0` |\n| `MONARC_NETWORK_NAME` | Shared Docker network name | `monarc-network` |\n| `NODE_MAJOR` | Node.js major version for frontend tools | `16` |\n| `STATS_HOST` | Stats service host | `0.0.0.0` |\n| `STATS_PORT` | Stats service port | `5005` |\n| `STATS_DB_NAME` | Stats database name | `statsservice` |\n| `STATS_DB_USER` | Stats database user | `sqlmonarcuser` |\n| `STATS_DB_PASSWORD` | Stats database password | `sqlmonarcuser` |\n| `STATS_SECRET_KEY` | Stats service secret key | `changeme_generate_random_secret_key_for_production` |\n| `XDEBUG_ENABLED` | Enable Xdebug in the build (`1/0`, `true/false`, `yes/no`) | `1` |\n| `XDEBUG_MODE` | Xdebug modes (`debug`, `develop`, etc.) | `debug` |\n| `XDEBUG_START_WITH_REQUEST` | Start mode (`trigger` or `yes`) | `trigger` |\n| `XDEBUG_CLIENT_HOST` | Host IDE address | `host.docker.internal` |\n| `XDEBUG_CLIENT_PORT` | IDE port | `9003` |\n| `XDEBUG_IDEKEY` | IDE key | `IDEKEY` |\n| `XDEBUG_DISCOVER_CLIENT_HOST` | Auto-detect client host (`1/0`) | `0` |\n\n## Security Notes\n\n⚠️ **Important**: The default credentials provided are for development only. Never use these in production!\n\nFor production deployments:\n1. Change all default passwords\n2. Generate a secure `STATS_SECRET_KEY` using `openssl rand -hex 32`\n3. Use proper SSL/TLS certificates\n4. Follow security best practices\n\n## Additional Resources\n\n- [MONARC Website](https://www.monarc.lu)\n- [MONARC Documentation](https://www.monarc.lu/documentation)\n- [GitHub Repository](https://github.com/monarc-project/MonarcAppFO)\n- [MonarcAppBO (BackOffice)](https://github.com/monarc-project/MonarcAppBO)\n\n## Getting Help\n\nIf you encounter issues:\n\n1. Check the [troubleshooting section](#troubleshooting)\n2. Review the logs: `docker compose -f docker-compose.dev.yml logs`\n3. Open an issue on [GitHub](https://github.com/monarc-project/MonarcAppFO/issues)\n4. Join the community discussions on [GitHub](https://github.com/monarc-project/MonarcAppFO/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonarc-project%2Fmonarcappfo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonarc-project%2Fmonarcappfo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonarc-project%2Fmonarcappfo/lists"}