From 552f67da65fd8c404174cc92e9ccb98e7b086c91 Mon Sep 17 00:00:00 2001 From: corelgott Date: Tue, 27 Aug 2024 18:23:15 +0200 Subject: [PATCH] docs: Manual Update and docker-compose cleanup (#61) * Added command to trigger a manual report update. Removes verison-tag from docker-compose, since its deprecated * chore: Added docker-compose examples and env-file - Added examples-folder - Added an example for a docker-compose with mysql - Added an example for a docker-compose with postgres - Extracted the most important variables to an env.example file - Added some documentation on how to use the env-file and the compose files --- README.md | 57 ++++++++-------------------- examples/docker-compose.mysql.yml | 39 +++++++++++++++++++ examples/docker-compose.postgres.yml | 37 ++++++++++++++++++ examples/env.example | 23 +++++++++++ 4 files changed, 115 insertions(+), 41 deletions(-) create mode 100644 examples/docker-compose.mysql.yml create mode 100644 examples/docker-compose.postgres.yml create mode 100644 examples/env.example diff --git a/README.md b/README.md index 8af27c8..3a6e533 100644 --- a/README.md +++ b/README.md @@ -40,53 +40,28 @@ CAUTION: The old gutmensch/dmarc-report:latest image (older alpine, php5, etc.) ## Sample docker compose / Environment variables -The variables should be self-explanatory. Make sure to create the IMAP folders before the cron job runs! +Make sure to create the IMAP-Folders for processed and error reports before the cron job runs! -**docker-compose.yml** +The default foldernames are are [`error`](examples/env.example) & [`processed`](examples/env.example) but they can be changed within the [`env-file`](examples/env.example). -```yaml -version: "3.6" +Make sure to rename the [`env.example`](examples/env.example) file to `.env` and adjust the values to your needs. -services: - dmarc-report: - image: "gutmensch/dmarc-report:latest" - hostname: dmarc-report - container_name: dmarc-report - depends_on: - - db - ports: - - "80:80" - environment: - - "REPORT_DB_HOST=db" - - "REPORT_DB_PORT=3306" - - "REPORT_DB_NAME=dmarc_report" - - "REPORT_DB_USER=dmarc_report" - - "REPORT_DB_PASS=dbpassword" - - "PARSER_IMAP_SERVER=mail" - - "PARSER_IMAP_PORT=143" - - "PARSER_IMAP_USER=foobar@example.com" - - "PARSER_IMAP_PASS=foobar" - - "PARSER_IMAP_READ_FOLDER=Inbox" - - "PARSER_IMAP_MOVE_FOLDER=processed" - - "PARSER_IMAP_MOVE_FOLDER_ERR=error" +You can find templates for both, [`postgreql`](examples/docker-compose.postgres.yml) + and [`mysql`](examples/docker-compose.mysql.yml) + db in the [`examples`](examples) directory. Just rename the setup you want to use to `docker-compose.yml`. - db: - image: mariadb:10 - command: --skip-innodb-read-only-compressed - environment: - - "MYSQL_ROOT_PASSWORD=dbrootpassword" - - "MYSQL_DATABASE=dmarc_report" - - "MYSQL_USER=dmarc_report" - - "MYSQL_PASSWORD=dbpassword" - volumes: - - ./dmarc-report-db:/var/lib/mysql - healthcheck: - test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-pdbrootpassword"] - interval: 10s - timeout: 10s - retries: 5 + + + +## Manual update + +If you are using the docker-compose file above, you can use this command to trigger an manual update. It will fetch the latest reports and parse them. + +```bash +docker compose exec dmarc-report /usr/bin/dmarcts-report-parser.pl -i -d -r=1 ``` + ## Optional extended configuration Use SSL instead of default TLS. Set both to 0 to turn off encryption. (not recommended) diff --git a/examples/docker-compose.mysql.yml b/examples/docker-compose.mysql.yml new file mode 100644 index 0000000..c784fdf --- /dev/null +++ b/examples/docker-compose.mysql.yml @@ -0,0 +1,39 @@ +services: + dmarc-report: + image: "gutmensch/dmarc-report:latest" + hostname: dmarc-report + container_name: dmarc-report + depends_on: + db: + condition: service_healthy + ports: + - "80:80" + environment: + - "REPORT_DB_HOST=db" + - "REPORT_DB_PORT=3306" + - "REPORT_DB_NAME=dmarc_report" + - "REPORT_DB_USER=dmarc_report" + - "REPORT_DB_PASS=${DMARC_DB_PASSWORD}" + - "PARSER_IMAP_SERVER=mail" + - "PARSER_IMAP_PORT=143" + - "PARSER_IMAP_USER=${DMARC_EMAIL}" + - "PARSER_IMAP_PASS=${DMARC_PASSWORD}" + - "PARSER_IMAP_READ_FOLDER=Inbox" + - "PARSER_IMAP_MOVE_FOLDER=${IMAP_MOVE_FOLDER:-processed}" + - "PARSER_IMAP_MOVE_FOLDER_ERR=${IMAP_MOVE_FOLDER_ERR:-error}" + + db: + image: mariadb:10 + command: --skip-innodb-read-only-compressed + environment: + - "MYSQL_ROOT_PASSWORD=${ROOT_DB_PASSWORD}" + - "MYSQL_DATABASE=dmarc_report" + - "MYSQL_USER=dmarc_report" + - "MYSQL_PASSWORD=${DMARC_DB_PASSWORD}" + volumes: + - ./run/db:/var/lib/mysql + healthcheck: + test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-pdbrootpassword"] + interval: 10s + timeout: 10s + retries: 5 \ No newline at end of file diff --git a/examples/docker-compose.postgres.yml b/examples/docker-compose.postgres.yml new file mode 100644 index 0000000..8dba293 --- /dev/null +++ b/examples/docker-compose.postgres.yml @@ -0,0 +1,37 @@ +services: + dmarc-report: + image: "gutmensch/dmarc-report:latest" + hostname: dmarc-report + container_name: dmarc-report + depends_on: + db: + condition: service_healthy + ports: + - "80:80" + environment: + - "REPORT_DB_TYPE=pgsql" + - "REPORT_DB_PORT=5432" + - "REPORT_DB_NAME=dmarc_report" + - "REPORT_DB_USER=dmarc_report" + - "REPORT_DB_PASS=${DMARC_DB_PASSWORD}" + - "PARSER_IMAP_SERVER=${IMAP_SERVER}" + - "PARSER_IMAP_PORT=${IMAP_PORT:-993}" + - "PARSER_IMAP_USER=${DMARC_EMAIL}" + - "PARSER_IMAP_PASS=${DMARC_PASSWORD}" + - "PARSER_IMAP_READ_FOLDER=Inbox" + - "PARSER_IMAP_MOVE_FOLDER=${IMAP_MOVE_FOLDER:-processed}" + - "PARSER_IMAP_MOVE_FOLDER_ERR=${IMAP_MOVE_FOLDER_ERR:-error}" + + db: + image: postgres:latest + environment: + - "POSTGRES_DB=dmarc_report" + - "POSTGRES_USER=dmarc_report" + - "POSTGRES_PASSWORD=${DMARC_DB_PASSWORD}" + volumes: + - ./run/db:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U dmarc_report"] + interval: 10s + timeout: 10s + retries: 5 \ No newline at end of file diff --git a/examples/env.example b/examples/env.example new file mode 100644 index 0000000..67d8cc7 --- /dev/null +++ b/examples/env.example @@ -0,0 +1,23 @@ +# mysql root password. Irrelevant if you are using postgres +ROOT_DB_PASSWORD= + +# database password for the dmarc user +DMARC_DB_PASSWORD= + +# the email address receiving the DMARC reports +DMARC_EMAIL= + +# the password for the email address receiving the DMARC reports +DMARC_PASSWORD= + +# the server the email address is hosted on +IMAP_SERVER= + +# optional: default is 993 +IMAP_PORT= + +# optional: default is "processed" +IMAP_MOVE_FOLDER= + +# optional: default is "error" +IMAP_MOVE_FOLDER_ERR= \ No newline at end of file