From e782805601abdcae52e79300c3efb3f6c4fa28da Mon Sep 17 00:00:00 2001 From: MAGIC Date: Wed, 6 Mar 2019 18:53:14 +0100 Subject: [PATCH] Add docs for migration --- docs/{install.md => i_u_m_install.md} | 144 ++++++++-------- docs/i_u_m_migration.md | 39 +++++ docs/{install-update.md => i_u_m_update.md} | 180 ++++++++++---------- mkdocs.yml | 9 +- 4 files changed, 206 insertions(+), 166 deletions(-) rename docs/{install.md => i_u_m_install.md} (97%) create mode 100644 docs/i_u_m_migration.md rename docs/{install-update.md => i_u_m_update.md} (96%) diff --git a/docs/install.md b/docs/i_u_m_install.md similarity index 97% rename from docs/install.md rename to docs/i_u_m_install.md index 059b7c51e..9702d3f0d 100644 --- a/docs/install.md +++ b/docs/i_u_m_install.md @@ -1,72 +1,72 @@ -!!! warning - Make sure you've read ["Prepare Your System"](https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-system) before proceeding! - - -You need Docker and Docker Compose. - -**1\.** Learn how to install [Docker](https://docs.docker.com/engine/installation/linux/) and [Docker Compose](https://docs.docker.com/compose/install/). - -Quick installation for most operation systems: - -- Docker -``` -curl -sSL https://get.docker.com/ | CHANNEL=stable sh -# After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7) -systemctl enable docker.service -systemctl start docker.service -``` - -- Docker-Compose -``` -curl -L https://github.com/docker/compose/releases/download/$(curl -Ls https://www.servercow.de/docker-compose/latest.php)/docker-compose-$(uname -s)-$(uname -m) > /usr/local/bin/docker-compose -chmod +x /usr/local/bin/docker-compose -``` - -Please use the latest Docker engine available and do not use the engine that ships with your distros repository. - -**2\.** Clone the master branch of the repository, make sure your umask equals 0022. -``` -# umask -0022 -# cd /opt -# git clone https://github.com/mailcow/mailcow-dockerized -# cd mailcow-dockerized -``` - -**3\.** Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked. -``` -./generate_config.sh -``` - -**4\.** Change configuration if you want or need to. -``` -nano mailcow.conf -``` -If you plan to use a reverse proxy, you can, for example, bind HTTPS to 127.0.0.1 on port 8443 and HTTP to 127.0.0.1 on port 8080. - -You may need to stop an existing pre-installed MTA which blocks port 25/tcp. See [this chapter](https://mailcow.github.io/mailcow-dockerized-docs/firststeps-local_mta/) to learn how to reconfigure Postfix to run besides mailcow after a successful installation. - -**4\.1\.** OpenStack users and users with a MTU not equal to 1500: - -Edit `docker-compose.yml` and change the network settings according to your MTU. -Add the new driver_opts parameter like this: -``` -networks: - mailcow-network: - ... - driver_opts: - com.docker.network.driver.mtu: 1450 - ... -``` - -**5\.** Pull the images and run the composer file. The parameter `-d` will start mailcow: dockerized detached: -``` -docker-compose pull -docker-compose up -d -``` - -Done! - -You can now access **https://${MAILCOW_HOSTNAME}** with the default credentials `admin` + password `moohoo`. - -The database will be initialized right after a connection to MySQL can be established. +!!! warning + Make sure you've read ["Prepare Your System"](https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-system) before proceeding! + + +You need Docker and Docker Compose. + +**1\.** Learn how to install [Docker](https://docs.docker.com/engine/installation/linux/) and [Docker Compose](https://docs.docker.com/compose/install/). + +Quick installation for most operation systems: + +- Docker +``` +curl -sSL https://get.docker.com/ | CHANNEL=stable sh +# After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7) +systemctl enable docker.service +systemctl start docker.service +``` + +- Docker-Compose +``` +curl -L https://github.com/docker/compose/releases/download/$(curl -Ls https://www.servercow.de/docker-compose/latest.php)/docker-compose-$(uname -s)-$(uname -m) > /usr/local/bin/docker-compose +chmod +x /usr/local/bin/docker-compose +``` + +Please use the latest Docker engine available and do not use the engine that ships with your distros repository. + +**2\.** Clone the master branch of the repository, make sure your umask equals 0022. +``` +# umask +0022 +# cd /opt +# git clone https://github.com/mailcow/mailcow-dockerized +# cd mailcow-dockerized +``` + +**3\.** Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked. +``` +./generate_config.sh +``` + +**4\.** Change configuration if you want or need to. +``` +nano mailcow.conf +``` +If you plan to use a reverse proxy, you can, for example, bind HTTPS to 127.0.0.1 on port 8443 and HTTP to 127.0.0.1 on port 8080. + +You may need to stop an existing pre-installed MTA which blocks port 25/tcp. See [this chapter](https://mailcow.github.io/mailcow-dockerized-docs/firststeps-local_mta/) to learn how to reconfigure Postfix to run besides mailcow after a successful installation. + +**4\.1\.** OpenStack users and users with a MTU not equal to 1500: + +Edit `docker-compose.yml` and change the network settings according to your MTU. +Add the new driver_opts parameter like this: +``` +networks: + mailcow-network: + ... + driver_opts: + com.docker.network.driver.mtu: 1450 + ... +``` + +**5\.** Pull the images and run the composer file. The parameter `-d` will start mailcow: dockerized detached: +``` +docker-compose pull +docker-compose up -d +``` + +Done! + +You can now access **https://${MAILCOW_HOSTNAME}** with the default credentials `admin` + password `moohoo`. + +The database will be initialized right after a connection to MySQL can be established. diff --git a/docs/i_u_m_migration.md b/docs/i_u_m_migration.md new file mode 100644 index 000000000..1bc37df10 --- /dev/null +++ b/docs/i_u_m_migration.md @@ -0,0 +1,39 @@ +If you want to migrate your old mailcow installation to a new server you can follow this: + +**1\.** +Install [Docker](https://docs.docker.com/engine/installation/linux/) and [Docker Compose](https://docs.docker.com/compose/install/) on your new server. + +Quick installation for most operation systems: + +- Docker +``` +curl -sSL https://get.docker.com/ | CHANNEL=stable sh +# After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7) +systemctl enable docker.service +``` + +- docker-compose +``` +curl -L https://github.com/docker/compose/releases/download/$(curl -Ls https://www.servercow.de/docker-compose/latest.php)/docker-compose-$(uname -s)-$(uname -m) > /usr/local/bin/docker-compose +chmod +x /usr/local/bin/docker-compose +``` + +Please use the latest Docker engine available and do not use the engine that ships with your distros repository. + +**2\.** Make sure that Docker is stopped: +``` +systemctl status docker.service +``` + +**3\.** Run the following commands on the source machine (take care of adding the trailing slashes in the first path parameter as shown below!): +``` +rsync -aHhP --numeric-ids --delete /opt/mailcow-dockerized/ root@some.other.machine.net:/opt/mailcow-dockerized +rsync -aHhP --numeric-ids --delete /var/lib/docker/volumes/ root@some.other.machine.net:/var/lib/docker/volumes +``` + +**4\.** Shut down Mailcow via `docker-compose down` and stop Docker on the source machine. +**5\.** Repeat step 3 with the same commands (this will be much quicker than the first time). +**6\.** Start docker on the target machine `systemctl start docker.service`. +**7\.** Go into the /opt/mailcow-dockerized directory and run `docker-compose pull`. +**8\.** Start the whole mailcow stack with `docker-compose up -d` and everything should be fine. +**9\.** Change your DNS settings. diff --git a/docs/install-update.md b/docs/i_u_m_update.md similarity index 96% rename from docs/install-update.md rename to docs/i_u_m_update.md index 4e717833e..3a19b8131 100644 --- a/docs/install-update.md +++ b/docs/i_u_m_update.md @@ -1,90 +1,90 @@ -## Automatic update - -An update script in your mailcow-dockerized directory will take care of updates. - -But use it with caution! If you think you made a lot of changes to the mailcow code, you should use the manual update guide below. - -Run the update script: -``` -./update.sh -``` - -If it needs to, it will ask you how you wish to proceed. -Merge errors will be reported. -Some minor conflicts will be auto-corrected (in favour for the mailcow: dockerized repository code). - -### Options - -``` -# Check for updates -./update.sh --check - -# Update with merge strategy "ours" instead of "theirs" -# This will merge in favor for your local changes. -./update.sh --ours -``` - -## Manual update - -### Step 1 - -You may want to backup your certificates, as an upgrade from an older mailcow: dockerized version may remove these files: - -``` -cp -rp data/assets/ssl /tmp/ssl_backup_mailcow -``` - -Fetch new data from GitHub, commit changes and merge remote repository: - -``` -# 1. Get updates/changes -git fetch origin master -# 2. Add all changed files to local clone -git add -A -# 3. Commit changes, ignore git complaining about username and mail address -git commit -m "Local config at $(date)" -# 4. Merge changes, prefer mailcow repository, replace "theirs" by "ours" to change merge strategy -git merge -Xtheirs -Xpatience - -# If it conflicts with files that were deleted from the mailcow repository, just run... -git status --porcelain | grep -E "UD|DU" | awk '{print $2}' | xargs rm -v -# ...and repeat step 2 and 3 -``` - -Check data/assets/ssl for your certificates (and dhparams.pem). If you miss them, recover your files: - -``` -cp -rp /tmp/ssl_backup_mailcow/* data/assets/ssl/ -``` - -### Step 2 - -When upgrading from a version older than May 13th, 2017 to a version released after that date, you need to run the following command first as network settings have been changed: - -``` -docker-compose down -``` - -Pull new images (if any) and recreate changed containers: - -``` -docker-compose pull -docker-compose up -d --remove-orphans -``` - -### Step 3 -Clean-up dangling (unused) images and volumes: - -It is **very important** to _not_ run these commands when your containers are deleted. -Running `docker-compose down` - for example - will delete your containers. Your volumes are now in a dangling state! Running the commands shown below, _will_ remove your volumes and therefore your data. - - -``` -docker rmi -f $(docker images -f "dangling=true" -q) -docker volume rm $(docker volume ls -qf dangling=true) -``` - - -## Footnotes - -- There is no release cycle regarding updates. +## Automatic update + +An update script in your mailcow-dockerized directory will take care of updates. + +But use it with caution! If you think you made a lot of changes to the mailcow code, you should use the manual update guide below. + +Run the update script: +``` +./update.sh +``` + +If it needs to, it will ask you how you wish to proceed. +Merge errors will be reported. +Some minor conflicts will be auto-corrected (in favour for the mailcow: dockerized repository code). + +### Options + +``` +# Check for updates +./update.sh --check + +# Update with merge strategy "ours" instead of "theirs" +# This will merge in favor for your local changes. +./update.sh --ours +``` + +## Manual update + +### Step 1 + +You may want to backup your certificates, as an upgrade from an older mailcow: dockerized version may remove these files: + +``` +cp -rp data/assets/ssl /tmp/ssl_backup_mailcow +``` + +Fetch new data from GitHub, commit changes and merge remote repository: + +``` +# 1. Get updates/changes +git fetch origin master +# 2. Add all changed files to local clone +git add -A +# 3. Commit changes, ignore git complaining about username and mail address +git commit -m "Local config at $(date)" +# 4. Merge changes, prefer mailcow repository, replace "theirs" by "ours" to change merge strategy +git merge -Xtheirs -Xpatience + +# If it conflicts with files that were deleted from the mailcow repository, just run... +git status --porcelain | grep -E "UD|DU" | awk '{print $2}' | xargs rm -v +# ...and repeat step 2 and 3 +``` + +Check data/assets/ssl for your certificates (and dhparams.pem). If you miss them, recover your files: + +``` +cp -rp /tmp/ssl_backup_mailcow/* data/assets/ssl/ +``` + +### Step 2 + +When upgrading from a version older than May 13th, 2017 to a version released after that date, you need to run the following command first as network settings have been changed: + +``` +docker-compose down +``` + +Pull new images (if any) and recreate changed containers: + +``` +docker-compose pull +docker-compose up -d --remove-orphans +``` + +### Step 3 +Clean-up dangling (unused) images and volumes: + +It is **very important** to _not_ run these commands when your containers are deleted. +Running `docker-compose down` - for example - will delete your containers. Your volumes are now in a dangling state! Running the commands shown below, _will_ remove your volumes and therefore your data. + + +``` +docker rmi -f $(docker images -f "dangling=true" -q) +docker volume rm $(docker volume ls -qf dangling=true) +``` + + +## Footnotes + +- There is no release cycle regarding updates. diff --git a/mkdocs.yml b/mkdocs.yml index caf4be002..9e3b34c90 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: "mailcow: dockerized documentation" site_url: https://mailcow.github.io/mailcow-dockerized-docs/ -copyright: 'Copyright © 2018 André Peters' +copyright: 'Copyright © 2019 André Peters' repo_name: mailcow/mailcow-dockerized repo_url: https://github.com/mailcow/mailcow-dockerized edit_uri: ../mailcow-dockerized-docs/edit/master/docs/ @@ -24,9 +24,10 @@ nav: - 'Prerequisites': - 'Prepare Your System': 'prerequisite-system.md' - 'DNS Setup': 'prerequisite-dns.md' -- 'Installation & Update': - - 'Installation': 'install.md' - - 'Update': 'install-update.md' +- 'Installation, Update & Migration': + - 'Installation': 'i_u_m_install.md' + - 'Update': 'i_u_m_update.md' + - 'Migration': 'i_u_m_migration.md' - 'First Steps (optional)': - 'SSL': 'firststeps-ssl.md' - 'Rspamd Web UI': 'firststeps-rspamd_ui.md'