github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity

Image registry and setup update (#3233)

Browse source 
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
This commit is contained in:
Georg Lauterbach 2023-04-10 11:37:25 +02:00 committed by GitHub
parent dc8a08031f
commit 1e20e7c332
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 63 additions and 169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docker-compose.yml
View file

@ -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

123
docs/content/config/setup.sh.md
View file

@ -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 <CONTAINER NAME> 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 <CONTAINER NAME> 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 <EMAIL ADDRESS> [<PASSWORD>]
./setup.sh email update <EMAIL ADDRESS> [<PASSWORD>]
./setup.sh email del [ OPTIONS... ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>... ]
./setup.sh email restrict <add|del|list> <send|receive> [<EMAIL ADDRESS>]
./setup.sh email list
COMMAND alias :=
./setup.sh alias add <EMAIL ADDRESS> <RECIPIENT>
./setup.sh alias del <EMAIL ADDRESS> <RECIPIENT>
./setup.sh alias list
COMMAND quota :=
./setup.sh quota set <EMAIL ADDRESS> [<QUOTA>]
./setup.sh quota del <EMAIL ADDRESS>
COMMAND config :=
./setup.sh config dkim [ ARGUMENTS... ]
COMMAND relay :=
./setup.sh relay add-auth <DOMAIN> <USERNAME> [<PASSWORD>]
./setup.sh relay add-domain <DOMAIN> <HOST> [<PORT>]
./setup.sh relay exclude-domain <DOMAIN>
COMMAND fail2ban =
./setup.sh fail2ban
./setup.sh fail2ban ban <IP>
./setup.sh fail2ban unban <IP>
COMMAND debug :=
./setup.sh debug fetchmail
./setup.sh debug login <COMMANDS>
./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

16
docs/content/examples/tutorials/basic-installation.md
View file

@ -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`.

2
docs/content/usage.md
View file

@ -123,7 +123,7 @@ For an overview of commands to manage DMS config, run: `docker exec -it <CONTAIN
```console
$ ./setup.sh help
Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
Image 'ghcr.io/docker-mailserver/docker-mailserver:latest' not found. Pulling ...
SETUP(1)
NAME

2
docs/mkdocs.yml
View file

@ -128,7 +128,7 @@ nav:
- 'Rspamd' : config/security/rspamd.md
- 'Debugging': config/debugging.md
- 'Mail Delivery with POP3': config/pop3.md
- 'Your Friend setup.sh': config/setup.sh.md
- 'About setup.sh': config/setup.sh.md
- 'Advanced Configuration':
- 'Optional Configuration': config/advanced/optional-config.md
- 'Maintenance':

2
setup.sh
View file

@ -12,7 +12,7 @@ DESIRED_CONFIG_PATH=
DIR=$(pwd)
DMS_CONFIG='/tmp/docker-mailserver'
IMAGE_NAME=
DEFAULT_IMAGE_NAME='docker.io/mailserver/docker-mailserver:latest'
DEFAULT_IMAGE_NAME='ghcr.io/docker-mailserver/docker-mailserver:latest'
INFO=
PODMAN_ROOTLESS=false
USE_SELINUX=

83
target/bin/setup
View file

@ -1,7 +1,5 @@
#!/bin/bash
SCRIPT='setup'
set -euE -o pipefail
# shellcheck source=../scripts/helpers/index.sh
@ -13,89 +11,80 @@ function _usage
printf '%s' "${PURPLE}SETUP${RED}(${YELLOW}1${RED})
${ORANGE}NAME${RESET}
${SCRIPT:-${0}} - 'docker-mailserver' Administration & Configuration script
setup - 'docker-mailserver' Administration & Configuration CLI
${ORANGE}SYNOPSIS${RESET}
./${SCRIPT:-${0}} [ OPTIONS${RED}...${RESET} ] COMMAND [ help ${RED}|${RESET} ARGUMENTS${RED}...${RESET} ]
setup [ OPTIONS${RED}...${RESET} ] COMMAND [ help ${RED}|${RESET} ARGUMENTS${RED}...${RESET} ]
COMMAND ${RED}:=${RESET} { email ${RED}|${RESET} alias ${RED}|${RESET} quota ${RED}|${RESET} dovecot-master ${RED}|${RESET} config ${RED}|${RESET} relay ${RED}|${RESET} debug } SUBCOMMAND
${ORANGE}DESCRIPTION${RESET}
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.
This is the main administration command that you use for all your interactions with
'docker-mailserver'. Initial setup, configuration, and much more is done with this CLI tool.
Please note that this script executes most of its commands inside the container itself.
If it cannot find a running 'docker-mailserver' container, it will attempt to run one using
any available tags which include 'label=org.opencontainers.image.title=\"docker-mailserver\"'
and then run the necessary commands. If the tag for the container is not found, this script
will pull the '${LWHITE}:latest${RESET}' tag of '${LWHITE}docker.io/mailserver/docker-mailserver${RESET}'.
This tag refers to the latest release, see the tagging convention in the README under:
${BLUE}https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md${RESET}
You will be able to see detailed information about the script you're invoking and their
arguments by appending '${LWHITE}help${RESET}' after your command. Currently, this does not work with all scripts.
Most subcommands can provide additional information and examples by appending 'help'.
For example: 'setup email add help'
${RED}[${ORANGE}SUB${RED}]${ORANGE}COMMANDS${RESET}
${LBLUE}COMMAND${RESET} email ${RED}:=${RESET}
${0} email ${CYAN}add${RESET} <EMAIL ADDRESS> [<PASSWORD>]
${0} email ${CYAN}update${RESET} <EMAIL ADDRESS> [<PASSWORD>]
${0} email ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>${RED}...${RESET} ]
${0} email ${CYAN}restrict${RESET} <add${RED}|${RESET}del${RED}|${RESET}list> <send${RED}|${RESET}receive> [<EMAIL ADDRESS>]
${0} email ${CYAN}list${RESET}
setup email ${CYAN}add${RESET} <EMAIL ADDRESS> [<PASSWORD>]
setup email ${CYAN}update${RESET} <EMAIL ADDRESS> [<PASSWORD>]
setup email ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] <EMAIL ADDRESS> [ <EMAIL ADDRESS>${RED}...${RESET} ]
setup email ${CYAN}restrict${RESET} <add${RED}|${RESET}del${RED}|${RESET}list> <send${RED}|${RESET}receive> [<EMAIL ADDRESS>]
setup email ${CYAN}list${RESET}
${LBLUE}COMMAND${RESET} alias ${RED}:=${RESET}
${0} alias ${CYAN}add${RESET} <EMAIL ADDRESS> <RECIPIENT>
${0} alias ${CYAN}del${RESET} <EMAIL ADDRESS> <RECIPIENT>
${0} alias ${CYAN}list${RESET}
setup alias ${CYAN}add${RESET} <EMAIL ADDRESS> <RECIPIENT>
setup alias ${CYAN}del${RESET} <EMAIL ADDRESS> <RECIPIENT>
setup alias ${CYAN}list${RESET}
${LBLUE}COMMAND${RESET} quota ${RED}:=${RESET}
${0} quota ${CYAN}set${RESET} <EMAIL ADDRESS> [<QUOTA>]
${0} quota ${CYAN}del${RESET} <EMAIL ADDRESS>
setup quota ${CYAN}set${RESET} <EMAIL ADDRESS> [<QUOTA>]
setup quota ${CYAN}del${RESET} <EMAIL ADDRESS>
${LBLUE}COMMAND${RESET} dovecot-master ${RED}:=${RESET}
${0} dovecot-master ${CYAN}add${RESET} <USERNAME> [<PASSWORD>]
${0} dovecot-master ${CYAN}update${RESET} <USERNAME> [<PASSWORD>]
${0} dovecot-master ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] <USERNAME> [ <USERNAME>${RED}...${RESET} ]
${0} dovecot-master ${CYAN}list${RESET}
setup dovecot-master ${CYAN}add${RESET} <USERNAME> [<PASSWORD>]
setup dovecot-master ${CYAN}update${RESET} <USERNAME> [<PASSWORD>]
setup dovecot-master ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] <USERNAME> [ <USERNAME>${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} <DOMAIN> <USERNAME> [<PASSWORD>]
${0} relay ${CYAN}add-domain${RESET} <DOMAIN> <HOST> [<PORT>]
${0} relay ${CYAN}exclude-domain${RESET} <DOMAIN>
setup relay ${CYAN}add-auth${RESET} <DOMAIN> <USERNAME> [<PASSWORD>]
setup relay ${CYAN}add-domain${RESET} <DOMAIN> <HOST> [<PORT>]
setup relay ${CYAN}exclude-domain${RESET} <DOMAIN>
${LBLUE}COMMAND${RESET} fail2ban ${RED}:=${RESET}
${0} fail2ban ${RESET}
${0} fail2ban ${CYAN}ban${RESET} <IP>
${0} fail2ban ${CYAN}unban${RESET} <IP>
setup fail2ban ${RESET}
setup fail2ban ${CYAN}ban${RESET} <IP>
setup fail2ban ${CYAN}unban${RESET} <IP>
${LBLUE}COMMAND${RESET} debug ${RED}:=${RESET}
${0} debug ${CYAN}fetchmail${RESET}
${0} debug ${CYAN}login${RESET} <COMMANDS>
${0} debug ${CYAN}show-mail-logs${RESET}
setup debug ${CYAN}fetchmail${RESET}
setup debug ${CYAN}login${RESET} <COMMANDS>
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
}

2
test/tests/parallel/set3/scripts/setup_cli.bats
View file

@ -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" {