Portable, Server independent, Docker-based code to get the zorg Websites and Services up, running, and hosted.
Table of Contents
- 🧪 Debugging Docker Services
- 📄 The
/zorg-docker/resources-directory & files - 💿 Import/export SQL-dumps with MariaDB
Install git for your OS.
Following the official installation instructions for Docker.
Tip
On Ubuntu it's advised against installing via snap, as this may cause compatibility issues!
Ensure the Host machine's firewall is configured to expose & allow access through the required ports for different Docker Services:
Allow a port - or port range
(non-conclusive, depends on what ports: are set in the .env file)
sudo ufw allow 80 # webserver/reverseproxy http
sudo ufw allow 443 # webserver/reverseproxy https
sudo ufw allow 3306/tcp # db-Server
sudo ufw allow 6667/tcp # irc-Server
sudo ufw allow 6697/tcp # irc-Server (secure)
sudo ufw allow 21/tcp # ftp-Server | NOTE: 22 reserved for ssh
sudo ufw allow 25/tcp # postfix-smtp Server
sudo ufw allow 587/tcp # postfix-smtp Server (STARTTLS)
sudo ufw allow 27960/udp # quake3-ServerInspect all rules - i.e. allowed ports
% sudo ufw status
Status: active
To Action From
-- ------ ----
80 ALLOW Anywhere
443 ALLOW Anywhere
3306/tcp ALLOW Anywhere
6667/tcp ALLOW Anywhere
6697/tcp ALLOW Anywhere
21/tcp ALLOW Anywhere
27960/udp ALLOW Anywhere
587 ALLOW Anywhere
25 ALLOW Anywhere
80 (v6) ALLOW Anywhere (v6)
443 (v6) ALLOW Anywhere (v6)
3306/tcp (v6) ALLOW Anywhere (v6)
6667/tcp (v6) ALLOW Anywhere (v6)
6697/tcp (v6) ALLOW Anywhere (v6)
21/tcp (v6) ALLOW Anywhere (v6)
27960/udp (v6) ALLOW Anywhere (v6)
587 (v6) ALLOW Anywhere (v6)
25 (v6) ALLOW Anywhere (v6)For all Hosts (subdomains) on the main Domain, the correspoinding DNS A-records with IP must be set up.
Example A-records
mail.domain.ch. 600 IN MX 178.nn.nn.nn
*.domain.ch. 600 IN A 178.nn.nn.nn
www.domain.ch. 600 IN A 178.nn.nn.nn
dockerstatus.domain.ch. 600 IN A 178.nn.nn.nnOn production a proper setup with pointing DNS for the root domain to the server's IP-address, this should not be necessary. But locally with a dummy domain, the domain & hostnames must be added to the /etc/hosts-file:
Example `hosts`-entries
(adjust as per your .env settings)
127.0.0.1 zdocker.dev
127.0.0.1 status.zdocker.dev
127.0.0.1 www.zdocker.dev
127.0.0.1 db.zdocker.dev
127.0.0.1 ftp.zdocker.dev
127.0.0.1 irc.zdocker.dev
127.0.0.1 pw.zdocker.dev
127.0.0.1 smtp.zdocker.dev
127.0.0.1 quake.zdocker.devIn general make sure to work from the project root directory:
cd /srv/<my-website>/<host>
Creat the a folder structure on your host machine that reflects the following:
Important
This is just a proposal, folder structures & names can be different!
└── www <-- (Your project root directory)
│
├── zorg-docker/ <-- Pulled Git repository (repo)
│
├── .env <-- Copy & adjust ".env.example" from repo
├── docker-compose.yml <-- Symbolic-linked ./zorg-docker/docker-compose.yml
├── docker-update.sh <-- Symbolic-linked ./zorg-docker/docker-update.sh
│
├── code-docu/
│ ├── code/ <-- (Optional) Git clone of github.com/zorgch/zorg-code.git. Reference in .env
│ ├── docu/ <-- (Optional) Reference in .env
│ └── phpdoc.xml <-- (Optional)
│
├── website/ <-- zorg Website configs & data
│ ├── .env <-- .env file for Website
│ ├── apache.conf <-- Copy & adjust "website/apache/example.conf" from repo
│ │ └── data/ <-- Website /data/ folder & files
│ │ ├── files/ (user generated content for zorg website)
│ │ ├── gallery/
│ │ ├── tauschboerse/
│ │ └── ...
│ │
│ ├── cronjobs/
│ │ └── cronjobs.crontab <-- Copy & adjust "website/php/example.crontab" from repo
│ ├── modsec/
│ │ └── WAF-REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf <-- (Optional)
│ │ └── WAF-RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf <-- (Optional)
│ └── sendmail/
│ └── msmtprc <-- Copy & adjust "website/sendmail/example-msmtprc" from repo
│
├── irc/
│ ├── anope-configs/ <-- Copy & adjust "irc/anope-example-sensitive-includes" from repo
│ │ ├── sensitive-channels.conf
│ │ ├── sensitive-mail.conf
│ │ ├── sensitive-networkinfo.conf
│ │ ├── sensitive-nicknames.conf
│ │ ├── sensitive-operators.conf
│ │ ├── sensitive-serverinfo.conf
│ │ ├── sensitive-uplink.conf
│ │ └── services.motd
│ └── ircd-configs/ <-- Copy & adjust "irc/unrealircd-example-sensitive-includes" from repo
│ ├── ircd.motd
│ ├── sensitive-admin.conf
│ ├── sensitive-history.conf
│ ├── sensitive-me.conf
│ ├── sensitive-network.conf
│ ├── sensitive-operators.conf
│ ├── sensitive-server.conf
│ └── sensitive-servicelink.conf
│
├── keepass/ <-- Reference in.env. Only AFTER sftp started: put kdbx file here.
│
├──quake3-baseq3/
│ ├── autoexec.cfg <-- Copy & adjust "quake3/example-server.cfg" from repo
│ ├── pak0.pk3 <-- From a local licensed Quake3 installation
│ └── pak1-8.pk3 <-- Can be obtained at: https://ioquake3.org/extras/patch-data/
│
└── logs/ <-- Reference in .env
├── cron/ <-- Sub-directories MUST also be created manually!
├── ircserver/
├── mailserver/
├── website/
│ ├── apache/
│ ├── php/
│ └── website/
├── sftp/
└── quake3-server/
Here's an overview of the underlaying Docker images used for the Docker Services, in order to provide quick access to their documentation & configuration how-to's.
Click to show list
| Service | Docker image | Link |
|---|---|---|
sslcerts |
alpine/mkcert |
GitHub |
dashboard |
portainer/portainer-ce |
Docs |
reverseproxy |
traefik |
Docs |
reverseproxy-waf |
owasp/modsecurity-crs |
GitHub |
website |
php |
Docker Hub |
db |
mariadb |
Docs |
postfix-smtp |
mailserver/docker-mailserver |
Docs |
irc |
c0dy/unrealircd-anope |
Docker Hub |
irc-quizbot |
python:2.7-slim |
GitHub |
stockticker |
python:3.9-slim |
GitHub |
servicealerts |
lorcas/docker-telegram-notifier |
GitHub |
sftp |
atmoz/sftp |
Docker Hub |
quake3 |
jberrenberg/quake3 |
GitHub |
phpdoc |
phpdoc/phpdoc |
Docs |
git clone -b <branch-name> --depth 1 https://github.com/zorgch/zorg-docker.git ./zorg-dockerNote
See below section for how to UPDATE the cloned git repository to get its latest changes.
cp ./zorg-docker/.env.example ./zorg-docker/.envImportant
Using your text editor of choice, adjust the .env-file to the setup of your host machine.
ln -s ./zorg-docker/docker-compose.yml ./docker-compose.ymldocker compose buildSome services require self-signed certificates, this does not interfere with (also) using Let's Encrypt certificates!
Add these first using the sslcerts service:
docker compose --profile setup upNote
This requires the mailserver service to be running!
Tip
This is required when emails to a local user (alias) should be forwarded to an external email address corresponding to that alias.
docker exec -ti PROJECTNAME-mailserver setup email add info@DOMAINNAME <NEW_PASSWORD>
docker exec -ti PROJECTNAME-mailserver setup alias add <EMAILADDRESS> <RECIPIENT>
The docker-mailserver setup is required for various configurations, including for example DKIM.
docker exec -ti PROJECTNAME-mailserver setup
docker exec -ti PROJECTNAME-mailserver setup config dkim help
cd into the directory containing the locally cloned git files, and run a git pull:
cd /srv/<my-website>/<host>/zorg-docker
git pull --rebasePRODUCTION mode – run in "detached mode" (background), without interative logging to the shell by adding the -d flag.
Start/stop all services *
docker compose --profile all up -d- Applicable services:
servicealerts,dashboard,reverseproxy,reverseproxy-waf,website,db,postfix-smtp,irc,irc-quizbot,stockticker
Example: only the Webserver services
docker compose --profile webserver up -d- Applicable services:
servicealerts,dashboard,reverseproxy,reverseproxy-waf,website,db,postfix-smtp
Example 2: only the IRC services
docker compose --profile irc up -d- Applicable services:
servicealerts,dashboard,irc,irc-quizbot
Example 2: only the Mailserver services
docker compose --profile mailserver up -d- Applicable services:
servicealerts,dashboard,reverseproxy,postfix-smtp
Caution
Do not take an individual service down using --profile, target it specifically instead!docker compose reverseproxy-waf down
* As provisioning a KeePass KDBX via SFTP is not required for the general website hosting, the SFTP service (keepass) is separated from the overall services.
docker compose --profile keepass up -d
docker compose sftp down* Due to a potential high load on the server, the «Quake 3 Arena» Server (quake3) is separated from the general services.
docker compose --profile quake up -d
docker compose quake3 down* As the code generation is only run occassionally, the phpDoc service (phpdoc) is separated from the general services.
docker compose --profile docu up
# exits automaticallyThe docker-compose.yml file uses Docker Service-profiles to group services into logical groups.
- This allows to only start / stop a certain group of services at once.
- Yet individual docker services can still be targeted individually by referencing their service name.
Some single services have their own profile, in order to prevent them from starting/stopping when using docker compose without any --profile.
Tip
Multiple profiles can be combined: docker compose --profile webserver --profile irc up
| Profile | Applicablae Docker Services | Example Usage |
|---|---|---|
all |
All general services | --profile all |
setup |
sslcerts postfix-smtp |
--profile setup |
status |
servicealerts dashboard reverseproxy |
--profile status |
webserver |
servicealerts dashboard reverseproxy reverseproxy-waf website db postfix-smtp |
--profile webserver |
mailserver |
servicealerts dashboard reverseproxy postfix-smtp |
--profile mailserver |
irc |
servicealerts dashboard irc irc-quizbot |
--profile irc |
keepass |
servicealerts dashboard sftp |
--profile keepass |
quake |
servicealerts dashboard quake3 |
--profile quake |
docu |
phpdoc |
--profile docu |
| Single service | e.g. stockticker |
docker compose up -d stockticker |
This is particularly helpful to fine-tune the CPU & memory limits for the Docker services, which can be adjusted in the .env-file.
docker statsExample docker status output
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"
NAME CPU % MEM USAGE / LIMIT MEM %
zorg-reverseproxy 0.00% 69.01MiB / 1GiB 6.74%
zorg-reverseproxy-waf 0.03% 70.19MiB / 1GiB 6.85%
zorg-mariadb 0.01% 133.8MiB / 4GiB 3.27%
zorg-website 0.01% 8.855MiB / 4GiB 0.22%
zorg-dashboard 0.00% 27.06MiB / 1GiB 2.64%
zorg-mailserver 0.11% 39.41MiB / 256MiB 15.39%The full-fledged Docker Management Dashboard (Portainer) can be accessed at:
https://dockerstatus.DOMAINNAME
Host can be adjusted in the.env
cd into the directory containing the docker-compose.yml (symlink), and run this shell command:
Tip
The images can be scoped to update only services within a specific Docker services profile
cd /srv/<my-website>/<host>/
for image in $(docker compose --profile all config | awk '/image:/ { print $2 }'); do docker pull "$image"; done;Alternatively, use the docker-update.sh script (can also be run via Host's cron):
cd /srv/<my-website>/<host>/
./docker-update.shCaution
Updating Docker images will NOT renew running services - they have to be rebuilt!
For DEBUGGING mode – with an interactive log output to the active shell - omit the -d flag when starting services:
docker compose --file ./website/docker-compose.yml up <-- no -d flag
Contains site specific resources that are actively mapped from the Host to some of the Docker Services. But it also contains some example files that can be used to configure the services.
Examples of example files
irc/anope-example-*&irc/unrealircd-example-*--> MUST be adaptedwebsite/apache/example.conf--> use asapache.confwebsite/php/example.crontab--> use ascrontabwebsite/sendmail/example-msmtprc--> use asmsmtprcquake3/example-autoexec.cfg--> use asautoexec.cfg
The Docker services are just writing logs to the mapped /logs-directory, but logrotate must be configured on the Host machine.
A third-party SQL Manager (e.g. on macOS use SequelAce) or CLI application is required to connect to the MariaDB service under the specified host and port.
mysql -h <db.host.domain> -P 3306 -u MYSQL_USER -p MYSQL_DATABASE < /path/to/import-dump.sqlmysqldump -h <db.host.domain> -P 3306 -u MYSQL_USER -p MYSQL_DATABASE > /path/to/save-dump.sqlCopyright (C) 2024 zorg Verein https://github.com/zorgch
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
This program comes with ABSOLUTELY NO WARRANTY; for details read the README. This is free software, and you are welcome to redistribute it under certain conditions; see the LICENSE.