Move Agora to another machine

In short. Moving means a full backup on one side and a restore on the other. Three things matter: the database, the files (attachments) and the session secret. The license is taken over in one click.

Before you start #

• Plan a quiet moment: the site will be unavailable during the switch.
• Keep the old installation stopped but intact until the new one works.
• Prepare the new machine or the new panel server with the same license key: see Install with Docker, Install on Pelican, Install on Pterodactyl or Install on a host's Node.js server.
• Moving uses Agora's admin area: you must be the installation's owner to restore. The words (dump, SFTP, session secret) are in the glossary.

Steps #

On the old machine #

1. Administration → Agora → Backups → Download a dump now.

   <!-- CAPTURE C-070 -->

2. Copy the data files:

   • Docker (install.sh): docker cp agora:/app/.data ./agora-files (attachments, MDT files, map backgrounds, backups);
   • panel: download the app/.data/ folder over SFTP or with the file manager;
   • Node.js server: download the data/ folder (except data/pg, which is the database itself).

3. Note the session secret:

   • Docker: the AUTH_SECRET line of /opt/agora/.env;
   • panel: it is in .agora/, closed to the file manager. If you cannot get it, you will re-enter the secrets (see below).

4. Stop the old installation.

On the new machine (Docker) #

1. Create /opt/agora/ and copy the old .env into it (it keeps the key, session secret and database password).

2. Run install.sh: it keeps that .env and installs the rest.

3. Stop Agora (docker stop agora), restore the dump:

   Copy

   docker exec -i agora-db psql -U agora -v ON_ERROR_STOP=1 --single-transaction agora < dump.sql

4. Copy the files back: docker cp ./agora-files/. agora:/app/.data/, then cd /opt/agora && docker compose up -d (the start gives the files back to Agora's user).

On the new panel or Node.js server #

On a panel, you have no terminal to restore the database: you go through Agora's admin area.

1. Install the new Hub with the egg (or agora.mjs) and the same key, "Base de donnees" variable empty (see Install on Pelican), and start it until ✓ Ready in ….
2. Open it in your browser and do the setup (see Do the getting-started setup) to become an administrator. This account is temporary: the restore will replace it with the ones in the backup.
3. In Administration → Agora → Backups, Import a file with your dump, tick the confirmation box and confirm. If the dump is over 12 MB, drop it into the server's backup folder (app/.data/backups) with the file manager, then click Restore: see Backups and restore.
4. Drop the files: send the content of your old app/.data/ into the new app/.data/ folder, over SFTP or with the file manager.
5. Restart the server.

<!-- À CONFIRMER : DEM-1, voie panel vers panel non éprouvée : (1) la mise en route à refaire avant la restauration, (2) la connexion Discord après restauration quand le secret de session (AUTH_SECRET) du nouveau serveur diffère de l'ancien (secrets chiffrés illisibles), (3) dépôt de app/.data/ par le gestionnaire de fichiers, et dossier à copier sur un serveur Node.js (data/ hors data/pg ?). Test banc à faire. -->

Take over the license #

A key belongs to one installation. The new machine is seen as a new installation:

• in Administration → Agora, License block, click Release the old seat and retry;
• on a panel, you can also set Reprendre le siege to 1 for one start.

<!-- CAPTURE C-071 -->

<!-- CAPTURE C-072 -->

See Free a license seat.

You know it worked when… #

• The site opens on the new machine with your members, your forum and your settings from before.
• Administration → Agora shows your license as active, with no seat-taken message.
• The FiveM resource reconnects: Server → Players receives its signal.

If it does not work #

Going further #

If the site address changes #

1. Put the new address in Administration → Configuration → Agora resource, field Public Hub address (the site settings only show a read-only summary of it in Administration → Configuration → Site identity).
2. Add the new callback URL to your Discord application.
3. Redeploy the FiveM resource: the address is embedded in it. See Install the agora FiveM resource.

If the session secret changed #

Everyone must sign in again, and stored secrets become unreadable. Re-enter them: game database password (Server → Database), bot token (Administration → Configuration → Discord connection), PayPal, panel and SFTP. Regenerate the tablet secret and redeploy the resource.

Switching from a built-in to an external database (or the reverse) #

The principle is the same as a move: Agora backup, change of the Base de donnees variable, restart, restore. The steps are in Troubleshoot the Hub's built-in database, section "Switching to an external PostgreSQL database". <!-- À CONFIRMER : œuf tout-en-un (claude/pg-integre), BASE-INTEGREE §5 : procédure non éprouvée sur le banc -->

Changing the type of installation #

Agora's dump is an ordinary PostgreSQL file: it restores the same way whether you go from Docker to a panel, from a panel to Docker, or from one panel to another. Only the "install the new Hub" step changes. <!-- À CONFIRMER : restauration d'un dump entre Docker et panel, non éprouvée -->