Add docs for migration

docs/i_u_m_install.md

@@ -1,72 +1,72 @@
-!!! warning
+!!! warning
-    Make sure you've read ["Prepare Your System"](https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-system) before proceeding!
+    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.
+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/).
+**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:
+Quick installation for most operation systems:
-
+
-- Docker
+- Docker
-```
+```
-curl -sSL https://get.docker.com/ | CHANNEL=stable sh
+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)
+# 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 enable docker.service
-systemctl start docker.service
+systemctl start docker.service
-```
+```
-
+
-- Docker-Compose
+- 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
+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
+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.
+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.
+**2\.** Clone the master branch of the repository, make sure your umask equals 0022.
-```
+```
-# umask
+# umask
-0022
+0022
-# cd /opt
+# cd /opt
-# git clone https://github.com/mailcow/mailcow-dockerized
+# git clone https://github.com/mailcow/mailcow-dockerized
-# cd mailcow-dockerized
+# cd mailcow-dockerized
-```
+```
-
+
-**3\.** Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked.
+**3\.** Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked.
-```
+```
-./generate_config.sh
+./generate_config.sh
-```
+```
-
+
-**4\.** Change configuration if you want or need to.
+**4\.** Change configuration if you want or need to.
-```
+```
-nano mailcow.conf
+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.
+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.
+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:
+**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.
+Edit `docker-compose.yml` and change the network settings according to your MTU.
-Add the new driver_opts parameter like this:
+Add the new driver_opts parameter like this:
-```
+```
-networks:
+networks:
-  mailcow-network:
+  mailcow-network:
-    ...
+    ...
-    driver_opts:
+    driver_opts:
-      com.docker.network.driver.mtu: 1450
+      com.docker.network.driver.mtu: 1450
-    ...
+    ...
-```
+```
-
+
-**5\.** Pull the images and run the composer file. The parameter `-d` will start mailcow: dockerized detached:
+**5\.** Pull the images and run the composer file. The parameter `-d` will start mailcow: dockerized detached:
-```
+```
-docker-compose pull
+docker-compose pull
-docker-compose up -d
+docker-compose up -d
-```
+```
-
+
-Done!
+Done!
-
+
-You can now access **https://${MAILCOW_HOSTNAME}** with the default credentials `admin` + password `moohoo`.
+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.
+The database will be initialized right after a connection to MySQL can be established.

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.

docs/i_u_m_update.md

@@ -1,90 +1,90 @@
-## Automatic update
+## Automatic update
-
+
-An update script in your mailcow-dockerized directory will take care of updates.
+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.
+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:
+Run the update script:
-```
+```
-./update.sh
+./update.sh
-```
+```
-
+
-If it needs to, it will ask you how you wish to proceed.
+If it needs to, it will ask you how you wish to proceed.
-Merge errors will be reported.
+Merge errors will be reported.
-Some minor conflicts will be auto-corrected (in favour for the mailcow: dockerized repository code).
+Some minor conflicts will be auto-corrected (in favour for the mailcow: dockerized repository code).
-
+
-### Options
+### Options
-
+
-```
+```
-# Check for updates
+# Check for updates
-./update.sh --check
+./update.sh --check
-
+
-# Update with merge strategy "ours" instead of "theirs" 
+# Update with merge strategy "ours" instead of "theirs" 
-# This will merge in favor for your local changes.
+# This will merge in favor for your local changes.
-./update.sh --ours
+./update.sh --ours
-```
+```
-
+
-## Manual update
+## Manual update
-
+
-### Step 1
+### Step 1
-
+
-You may want to backup your certificates, as an upgrade from an older mailcow: dockerized version may remove these files:
+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
+cp -rp data/assets/ssl /tmp/ssl_backup_mailcow
-```
+```
-
+
-Fetch new data from GitHub, commit changes and merge remote repository:
+Fetch new data from GitHub, commit changes and merge remote repository:
-
+
-```
+```
-# 1. Get updates/changes
+# 1. Get updates/changes
-git fetch origin master
+git fetch origin master
-# 2. Add all changed files to local clone
+# 2. Add all changed files to local clone
-git add -A
+git add -A
-# 3. Commit changes, ignore git complaining about username and mail address
+# 3. Commit changes, ignore git complaining about username and mail address
-git commit -m "Local config at $(date)"
+git commit -m "Local config at $(date)"
-# 4. Merge changes, prefer mailcow repository, replace "theirs" by "ours" to change merge strategy
+# 4. Merge changes, prefer mailcow repository, replace "theirs" by "ours" to change merge strategy
-git merge -Xtheirs -Xpatience
+git merge -Xtheirs -Xpatience
-
+
-# If it conflicts with files that were deleted from the mailcow repository, just run...
+# 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
+git status --porcelain | grep -E "UD|DU" | awk '{print $2}' | xargs rm -v
-# ...and repeat step 2 and 3
+# ...and repeat step 2 and 3
-```
+```
-
+
-Check data/assets/ssl for your certificates (and dhparams.pem). If you miss them, recover your files:
+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/
+cp -rp /tmp/ssl_backup_mailcow/* data/assets/ssl/
-```
+```
-
+
-### Step 2
+### 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:
+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
+docker-compose down
-```
+```
-
+
-Pull new images (if any) and recreate changed containers:
+Pull new images (if any) and recreate changed containers:
-
+
-```
+```
-docker-compose pull
+docker-compose pull
-docker-compose up -d --remove-orphans
+docker-compose up -d --remove-orphans
-```
+```
-
+
-### Step 3
+### Step 3
-Clean-up dangling (unused) images and volumes:
+Clean-up dangling (unused) images and volumes:
-
+
-It is **very important** to _not_ run these commands when your containers are deleted.
+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.
+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 rmi -f $(docker images -f "dangling=true" -q)
-docker volume rm $(docker volume ls -qf dangling=true)
+docker volume rm $(docker volume ls -qf dangling=true)
-```
+```
-
+
-
+
-## Footnotes
+## Footnotes
-
+
-- There is no release cycle regarding updates.
+- There is no release cycle regarding updates.

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, Update & Migration':
-  - 'Installation': 'install.md'
+  - 'Installation': 'i_u_m_install.md'
-  - 'Update': 'install-update.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'