diff --git a/docker-compose.yml b/docker-compose.yml index 8834d37e..37c42c7c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,6 @@ services: mailserver: - image: docker.io/mailserver/docker-mailserver:latest + image: ghcr.io/docker-mailserver/docker-mailserver:latest container_name: mailserver # Provide the FQDN of your mail server here (Your DNS MX record should point to this value) hostname: mail.example.com diff --git a/docs/content/config/setup.sh.md b/docs/content/config/setup.sh.md index b55b7d9d..d0829bc8 100644 --- a/docs/content/config/setup.sh.md +++ b/docs/content/config/setup.sh.md @@ -1,123 +1,28 @@ --- -title: Your best friend setup.sh +title: About setup.sh hide: - toc --- -[`setup.sh`][github-file-setupsh] is an administration script that helps with the most common tasks, including initial configuration. It is intended to be run from the host machine, _not_ from inside your running container. +!!! note -The latest version of the script is included in the `docker-mailserver` repository. You may retrieve it at any time by running this command in your console: + `setup.sh` is not required. We encourage you to use `docker exec -ti setup` instead. + +!!! warning + + This script assumes Docker or Podman is used. You will not be able to use `setup.sh` with other container orchestration tools. + +[`setup.sh`][github-file-setupsh] is a script that is complimentary to the internal `setup` command in `docker-mailserver`. + +It mostly provides the convenience of aliasing `docker exec -ti setup`, inferring the container name of a running `docker-mailserver` instance or running a new instance and bind mounting necessary volumes implicitly. + +It is intended to be run from the host machine, _not_ from inside your running container. The latest version of the script is included in the `docker-mailserver` repository. You may retrieve it at any time by running this command in your console: ```sh wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh chmod a+x ./setup.sh ``` -## Usage - -Run `./setup.sh help` and you'll get ~~all you have ever wanted~~ some usage information: - -```TXT -SETUP(1) - -NAME - setup.sh - docker-mailserver administration script - -SYNOPSIS - ./setup.sh [ OPTIONS... ] COMMAND [ help | ARGUMENTS... ] - - COMMAND := { email | alias | quota | config | relay | debug } SUBCOMMAND - -DESCRIPTION - This is the main administration script that you use for all your interactions with - 'docker-mailserver'. Setup, configuration and much more is done with this script. - - Please note that the script executes most of the commands inside the container itself. - If the image was not found, this script will pull the ':latest' tag of - 'docker.io/mailserver/docker-mailserver'. This tag refers to the latest release, - see the tagging convention in the README under - https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md - - You will be able to see detailed information about the script you're invoking and - its arguments by appending help after your command. Currently, this - does not work with all scripts. - -[SUB]COMMANDS - COMMAND email := - ./setup.sh email add [] - ./setup.sh email update [] - ./setup.sh email del [ OPTIONS... ] [ ... ] - ./setup.sh email restrict [] - ./setup.sh email list - - COMMAND alias := - ./setup.sh alias add - ./setup.sh alias del - ./setup.sh alias list - - COMMAND quota := - ./setup.sh quota set [] - ./setup.sh quota del - - COMMAND config := - ./setup.sh config dkim [ ARGUMENTS... ] - - COMMAND relay := - ./setup.sh relay add-auth [] - ./setup.sh relay add-domain [] - ./setup.sh relay exclude-domain - - COMMAND fail2ban = - ./setup.sh fail2ban - ./setup.sh fail2ban ban - ./setup.sh fail2ban unban - - COMMAND debug := - ./setup.sh debug fetchmail - ./setup.sh debug login - ./setup.sh debug show-mail-logs - -EXAMPLES - ./setup.sh email add test@example.com [password] - Add the email account test@example.com. You will be prompted - to input a password afterwards if no password was supplied. - When supplying `[password]`, it should be in plaintext. - - ./setup.sh config dkim keysize 2048 domain 'example.com,not-example.com' - Creates keys of length 2048 but in an LDAP setup where domains are not known to - Postfix by default, so you need to provide them yourself in a comma-separated list. - - ./setup.sh config dkim help - This will provide you with a detailed explanation on how to use the - config dkim command, showing what arguments can be passed and what they do. - -OPTIONS - Config path, container or image adjustments - -i IMAGE_NAME - Provides the name of the 'docker-mailserver' image. The default value is - 'docker.io/mailserver/docker-mailserver:latest' - - -c CONTAINER_NAME - Provides the name of the running container. - - -p PATH - Provides the config folder path to the temporary container - (does not work if a 'docker-mailserver' container already exists). - - SELinux - -z - Allows container access to the bind mount content that is shared among - multiple containers on a SELinux-enabled host. - - -Z - Allows container access to the bind mount content that is private and - unshared with other containers on a SELinux-enabled host. - -EXIT STATUS - Exit status is 0 if the command was successful. If there was an unexpected error, an error - message is shown describing the error. In case of an error, the script will exit with exit - status 1. - -``` +For more information on using the script run: `./setup.sh help`. [github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh diff --git a/docs/content/examples/tutorials/basic-installation.md b/docs/content/examples/tutorials/basic-installation.md index bdb7cfb3..31c64961 100644 --- a/docs/content/examples/tutorials/basic-installation.md +++ b/docs/content/examples/tutorials/basic-installation.md @@ -103,7 +103,7 @@ In this setup `docker-mailserver` is not intended to receive email from the outs ```yaml services: mailserver: - image: docker.io/mailserver/docker-mailserver:latest + image: ghcr.io/docker-mailserver/docker-mailserver:latest container_name: mailserver # Provide the FQDN of your mail server here (Your DNS MX record should point to this value) hostname: mail.example.com @@ -137,7 +137,7 @@ In this setup `docker-mailserver` is not intended to receive email from the outs ??? tip "Firewalled ports" If you have a firewall running, you may need to open ports `25`, `587` and `465`. - + For example, with the firewall `ufw`, run: ```sh @@ -145,27 +145,27 @@ In this setup `docker-mailserver` is not intended to receive email from the outs ufw allow 587 ufw allow 465 ``` - + **Caution:** This may [not be sound advice][github-issue-ufw]. 2. Configure your DNS service to use an MX record for the _hostname_ (eg: `mail`) you configured in the previous step and add the [SPF][docs-spf] TXT record. !!! tip "If you manually manage the DNS zone file for the domain" - + It would look something like this: - + ```txt $ORIGIN example.com @ IN A 10.11.12.13 mail IN A 10.11.12.13 - + ; mail-server for example.com @ IN MX 10 mail.example.com. - + ; Add SPF record @ IN TXT "v=spf1 mx -all" ``` - + Then don't forget to change the `SOA` serial number, and to restart the service. 3. [Generate DKIM keys][docs-dkim] for your domain via `setup config dkim`. diff --git a/docs/content/usage.md b/docs/content/usage.md index bc34f665..5b4f84a3 100644 --- a/docs/content/usage.md +++ b/docs/content/usage.md @@ -123,7 +123,7 @@ For an overview of commands to manage DMS config, run: `docker exec -it [] - ${0} email ${CYAN}update${RESET} [] - ${0} email ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] [ ${RED}...${RESET} ] - ${0} email ${CYAN}restrict${RESET} [] - ${0} email ${CYAN}list${RESET} + setup email ${CYAN}add${RESET} [] + setup email ${CYAN}update${RESET} [] + setup email ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] [ ${RED}...${RESET} ] + setup email ${CYAN}restrict${RESET} [] + setup email ${CYAN}list${RESET} ${LBLUE}COMMAND${RESET} alias ${RED}:=${RESET} - ${0} alias ${CYAN}add${RESET} - ${0} alias ${CYAN}del${RESET} - ${0} alias ${CYAN}list${RESET} + setup alias ${CYAN}add${RESET} + setup alias ${CYAN}del${RESET} + setup alias ${CYAN}list${RESET} ${LBLUE}COMMAND${RESET} quota ${RED}:=${RESET} - ${0} quota ${CYAN}set${RESET} [] - ${0} quota ${CYAN}del${RESET} + setup quota ${CYAN}set${RESET} [] + setup quota ${CYAN}del${RESET} ${LBLUE}COMMAND${RESET} dovecot-master ${RED}:=${RESET} - ${0} dovecot-master ${CYAN}add${RESET} [] - ${0} dovecot-master ${CYAN}update${RESET} [] - ${0} dovecot-master ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] [ ${RED}...${RESET} ] - ${0} dovecot-master ${CYAN}list${RESET} + setup dovecot-master ${CYAN}add${RESET} [] + setup dovecot-master ${CYAN}update${RESET} [] + setup dovecot-master ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] [ ${RED}...${RESET} ] + setup dovecot-master ${CYAN}list${RESET} ${LBLUE}COMMAND${RESET} config ${RED}:=${RESET} - ${0} config ${CYAN}dkim${RESET} [ ARGUMENTS${RED}...${RESET} ] + setup config ${CYAN}dkim${RESET} [ ARGUMENTS${RED}...${RESET} ] ${LBLUE}COMMAND${RESET} relay ${RED}:=${RESET} - ${0} relay ${CYAN}add-auth${RESET} [] - ${0} relay ${CYAN}add-domain${RESET} [] - ${0} relay ${CYAN}exclude-domain${RESET} + setup relay ${CYAN}add-auth${RESET} [] + setup relay ${CYAN}add-domain${RESET} [] + setup relay ${CYAN}exclude-domain${RESET} ${LBLUE}COMMAND${RESET} fail2ban ${RED}:=${RESET} - ${0} fail2ban ${RESET} - ${0} fail2ban ${CYAN}ban${RESET} - ${0} fail2ban ${CYAN}unban${RESET} + setup fail2ban ${RESET} + setup fail2ban ${CYAN}ban${RESET} + setup fail2ban ${CYAN}unban${RESET} ${LBLUE}COMMAND${RESET} debug ${RED}:=${RESET} - ${0} debug ${CYAN}fetchmail${RESET} - ${0} debug ${CYAN}login${RESET} - ${0} debug ${CYAN}show-mail-logs${RESET} + setup debug ${CYAN}fetchmail${RESET} + setup debug ${CYAN}login${RESET} + setup debug ${CYAN}show-mail-logs${RESET} ${ORANGE}EXAMPLES${RESET} - ${LWHITE}./setup.sh email add test@example.com${RESET} + ${LWHITE}setup email add test@example.com${RESET} Add the email account ${LWHITE}test@example.com${RESET}. You will be prompted to input a password afterwards since no password was supplied. - ${LWHITE}./setup.sh config dkim keysize 2048 domain 'example.com,not-example.com'${RESET} - Creates keys of length 2048 but in an LDAP setup where domains are not known to - Postfix by default, so you need to provide them yourself in a comma-separated list. + ${LWHITE}setup config dkim keysize 2048 domain 'example.com,not-example.com'${RESET} + Creates keys of length 2048 for the domains in comma-seperated list. + This is necessary when using LDAP as the required domains cannot be inferred. - ${LWHITE}./setup.sh config dkim help${RESET} + ${LWHITE}setup config dkim help${RESET} This will provide you with a detailed explanation on how to use the ${LWHITE} config dkim${RESET} command, showing what arguments can be passed and what they do. " } - function _invalid_command { echo "The command '${*}' is invalid. -Use \`./setup.sh help\` to get an overview of all commands." >&2 +Use \`setup help\` to get an overview of all commands." >&2 exit 2 } diff --git a/test/tests/parallel/set3/scripts/setup_cli.bats b/test/tests/parallel/set3/scripts/setup_cli.bats index 737bf53d..c5d2a2d6 100644 --- a/test/tests/parallel/set3/scripts/setup_cli.bats +++ b/test/tests/parallel/set3/scripts/setup_cli.bats @@ -28,7 +28,7 @@ function teardown_file() { _default_teardown ; } @test "show usage when no arguments provided" { run ./setup.sh assert_success - assert_output --partial "This is the main administration script that you use for all your interactions with" + assert_output --partial "This is the main administration command that you use for all your interactions with" } @test "exit with error when wrong arguments provided" {