Update, back up and move a NetSendo installation

Before you start

• You need a shell on the server. Run every command in the installation folder, the one that holds docker-compose.yml and .env. That is NetSendo for a git clone and netsendo for an install.sh install.
• Check how NetSendo was installed. A git clone gets new configuration files with git pull. An install.sh folder has no git history, so you download them instead.
• No licence plan is needed for anything on this page.
• The short versions are in Quick Start → Updating and Backups. This page adds restoring and moving.
• Settings → Updates, tab How to Update, shows a shorter list: stop, pull, start. That list has no backup step and leaves the configuration files as they are. The steps below follow DOCKER_INSTALL.md of 2.7.0.

What to keep:

You can skip redisdata, netsendo-public and netsendo-logs. redisdata does hold the job queue, though, so let the queue finish before you move the installation (Move to another server, step 1).

Steps

Back up

1. Dump the database into backups/db/ (the db container mounts that folder at /backups):

   docker compose exec db sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction "$MYSQL_DATABASE" > /backups/netsendo.sql'
   

2. Pack the uploaded files:

   docker compose exec -T app tar czf - -C /var/www/storage app > backups/netsendo-storage.tar.gz
   

   The archive includes NetSendo's own backups, in app/private/NetSendo with the default APP_NAME. To leave them out, add --exclude=app/private/NetSendo after czf -.
3. Copy .env:

   cp .env backups/env.backup
   

4. Copy the backups folder to another machine. The dump holds all your contact data, so keep it private.

To copy the dbdata volume itself instead of dumping it, stop the stack first. Restore such a copy only with the same MySQL image (mysql:8.4) and the same .env:

docker compose stop
docker run --rm --volumes-from netsendo-db -v "$PWD/backups":/out ubuntu tar czf /out/dbdata.tar.gz --numeric-owner -C /var/lib/mysql .

To put it back into a new, empty volume, run docker compose create db, then docker run --rm --volumes-from netsendo-db -v "$PWD/backups":/out ubuntu tar xzf /out/dbdata.tar.gz --numeric-owner -C /var/lib/mysql, then docker compose up -d.

NetSendo also has its own backups under Settings → Backups. Create Backup adds an archive to Available Backups. With Database only (faster backup) ticked (the default) the archive holds the database; untick it to include the application files too. The scheduler makes a full backup every day at 02:00 UTC and removes old ones at 03:30 UTC. These archives are stored in netsendo-storage on the same server, so click Download to keep a copy somewhere else.

Update to a new release

1. Dump the database (Back up, step 1). Migrations run when the app starts, and they cannot be undone.
2. Update the configuration files. In a git clone run git pull (or git fetch --tags and git checkout v2.7.0 to match a pinned release). In an install.sh folder, download them (your old copies stay as .bak):

   V=v2.7.0
   for f in docker-compose.yml docker/php/docker-entrypoint.sh docker/php/uploads.ini docker/nginx/default.conf; do
     cp "$f" "$f.bak" 2>/dev/null
     curl -fsSL "https://raw.githubusercontent.com/NetSendo/NetSendo/$V/$f" -o "$f"
   done
   chmod +x docker/php/docker-entrypoint.sh
   

   If you had changed one of these files, carry your change over from its .bak copy.
3. In .env, set NETSENDO_VERSION=2.7.0, or add the line if it is missing. install.sh writes this line itself. Without it the image tag is latest, which is built from the main branch whenever its code changes, not only at releases.
4. Compare .env with the release's .env.example for new settings. .env is never replaced.
5. Pull the images and start:

   docker compose pull
   docker compose up -d
   docker compose logs -f app
   

   The app container runs the pending migrations. scheduler, queue and reverb wait until it has finished. Press Ctrl+C to stop following the log. You do not need docker compose down, a frontend rebuild or clearing the cache.

Restore

1. Stop the containers that use the database:

   docker compose stop app scheduler queue reverb
   

2. Empty the database, then import the dump:

   docker compose exec db sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "DROP DATABASE $MYSQL_DATABASE; CREATE DATABASE $MYSQL_DATABASE;"'
   docker compose exec db sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" < /backups/netsendo.sql'
   

   The database user keeps its rights; MySQL does not remove them when a database is dropped.
3. To go back to the release you had before an update, set its number in NETSENDO_VERSION and put back the .bak copies, or the previous tag in a git clone.
4. Start everything with docker compose up -d.
5. If you also need the files back: docker compose exec -T app tar xzf - -C /var/www/storage < backups/netsendo-storage.tar.gz

Settings → Backups → Restore does the database part in the panel. It first makes a safety backup of the current database, then replaces the database, but not the files, with the archive's. The queue worker must be running.

Move to another server

1. On the old server, stop new sends: docker compose stop scheduler.
2. Let the queue run empty. With the default QUEUE_CONNECTION=redis, docker compose exec app php artisan queue:monitor redis:default,redis:notifications shows the number of waiting jobs. When both are 0, run docker compose stop queue.
3. Make the three backups (database, files, .env) as above, then run docker compose stop. Signups and unsubscribes that reach the old server after the dump are not copied, so keep this window short.
4. Copy the whole installation folder, backups included, to the new server. For example: rsync -a ./ user@new-server:/opt/netsendo/.
5. On the new server, install Docker Engine with the Compose plugin (Docker's install guide).
6. In the copied .env, keep APP_KEY, DB_DATABASE, DB_USERNAME, DB_PASSWORD and NETSENDO_VERSION as they are. Change APP_URL only if the address changes.
7. Start only the database: docker compose up -d db. Wait until docker compose ps db shows healthy.
8. Import the dump:

   docker compose exec db sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" < /backups/netsendo.sql'
   

9. Start the app: docker compose up -d app. Then put the files back with the tar xzf command from Restore, step 5.
10. Start the rest: docker compose up -d.
11. Set up the reverse proxy and HTTPS (Configuration → HTTPS), then point DNS at the new server.
12. Do not start the old stack again. Each server has its own copy of the database, so both would send the same scheduled messages.

If you use the nmi profile, also copy its DKIM keys and TLS certificates. On the old server, run docker run --rm --volumes-from netsendo-mta -v "$PWD/backups":/out ubuntu tar czf /out/nmi.tar.gz --numeric-owner /opt/haraka/config/dkim /opt/haraka/config/tls. On the new server, run docker compose --profile nmi create nmi-mta, then the same docker run with tar xzf /out/nmi.tar.gz --numeric-owner -C /. Then see SPF, DKIM and DMARC for the new IP address.

Check that it works

• docker compose ps lists every service as running, with app, webserver, db and redis marked healthy.
• docker compose exec app php artisan migrate:status shows no line marked Pending.
• In the panel, open Settings → Updates. Current Version shows the release, for example v2.7.0.
• An AI assistant connected through the NetSendo MCP server can confirm the version with get_account_info; the answer includes version.
• After a move, sign in at the new address, open a message with images, and send a test email.
• head -n 3 backups/db/netsendo.sql starts with a MySQL dump comment, and tar tzf backups/netsendo-storage.tar.gz | head lists app/… paths.

If it doesn't work

Access denied for user 'root' when you dump or import

MySQL sets the root password from DB_PASSWORD only the first time it starts on an empty volume. A later change to .env does not change it. Put back the password the database was created with.

scheduler, queue or reverb keep logging "Waiting for the app container to migrate the database..."

The app is still migrating, or a migration failed. Read docker compose logs app. After 1,800 seconds (NETSENDO_MIGRATIONS_WAIT_TIMEOUT) they start anyway.

The app log says "migration(s) still pending after 3 attempts"

A migration failed. The error is in the lines above. Restore the dump and stay on the old release until the problem is fixed.

The version did not change after docker compose pull

NETSENDO_VERSION in .env still names the old release.

A container does not start, and docker/php/docker-entrypoint.sh or uploads.ini is a folder

A file that docker-compose.yml mounts was missing, so Docker created a folder in its place. Delete the folder, download the file (Update, step 2), then run docker compose up -d.

"Table … already exists" after a move or restore

The app migrated the empty database before the import, using a newer release than the dump. Empty the database (Restore, step 2), import again, then start.

Mailboxes fail to log in, or AI and SMS keys stop working, after a move

APP_KEY differs from the old server. NetSendo cannot decrypt the saved credentials. Put the old key back and run docker compose up -d --force-recreate.

Settings → Backups stays on "Creating backup…" or says "Another backup operation is already running"

The backup runs on the queue. Start the worker with docker compose up -d queue and check docker compose logs queue.

A backup fails with a TLS/SSL error

Keep MYSQL_DUMP_SSL=false in .env, as in .env.example.