Install on Pelican

In short. You import Agora's egg into your Pelican panel (the file that tells the panel how to install Agora), you create a server with that egg, and you start it. You have no database to prepare: Agora provides and manages its own database inside the server, you simply leave the "Base de donnees" variable empty. The first start takes a few minutes.

Before you start #

• A Pelican panel where you are an administrator. Not sure it is Pelican, or you do not have the Administration menu? Read Tell Pelican and Pterodactyl apart first. With a host that does not let you import an egg, use a Node.js server instead.
• Your license key (it starts with AGORA-). The egg downloaded from your space already contains it. No key? The free trial is a real one: see The 14-day free trial.
• The server's resources: 2 GB of memory recommended (1.5 GB minimum) and 5 GB of disk (10 GB is more comfortable), because the server runs Agora and its database. With less, the panel may stop the server in the middle of its activity.
• A port allocation: the IP address and port the panel reserves for this server. They are what you will open your site on.
• An outgoing HTTPS connection to the Internet from the server (see Requirements).
• The words panel, egg, allocation and database are in the glossary; Agora's two databases are told apart in The two Agora databases.

Did you import Agora's egg a while ago? The old egg declared the "Base de donnees" variable as required: the panel refused to create a server without it. The new egg makes it optional. Import the egg again from your space before creating a new server. Servers already created with the old egg keep working as they are. <!-- À CONFIRMER : œuf tout-en-un (claude/pg-integre) ; comment réimporter sur un panel qui a déjà l'ancien œuf (créer un second œuf puis supprimer l'ancien, ou mettre à jour l'œuf existant) : à vérifier sur le banc Pelican -->

Steps #

1. Open the installation page of your space. On agorapanel.com, go to Install on my panel (My account → Install on my panel). Without a key, click Get my free trial key.

   <!-- CAPTURE C-047 -->

2. Download the Pelican egg. Click Egg for Pelican. The file agora-egg-pelican.json already contains your key: the site therefore first asks you to verify your session (see Activate or change your license key), then you click again.

3. Import it into Pelican. In the panel, open the Administration, then the list of Eggs, click Import and upload the file. <!-- À CONFIRMER : libellés exacts de l'import d'œuf sous Pelican (menu Eggs, bouton Import), vérification banc -->

   <!-- CAPTURE C-048 -->

4. Create the server. Still in the administration, open Servers and create a server. Pick the node (the machine that runs the panel's servers), the Agora egg, a free allocation, 2048 MB of memory and 10240 MB of disk. <!-- À CONFIRMER : libellés et unités du formulaire de création de serveur Pelican (Mo/Gio), vérification banc -->

   <!-- CAPTURE C-049 -->

5. Look at the server's variables. They show up at creation, then in the server's Startup tab. Their names are in French and have no accents, which is normal:

   • Cle de licence (AGORA_KEY): must hold your key. If you took the public egg without a key, paste it here;
   • Base de donnees (DATABASE_URL): leave it empty. Empty means "use your built-in database";
   • Canal de mise a jour and Mettre a jour au demarrage: keep the defaults (stable and 0).

   <!-- CAPTURE C-050 -->

6. Ignore the Databases tab. That tab of the server creates your game server's database (MySQL), never Agora's. Even if your panel offers PostgreSQL there, do not use it here. <!-- À CONFIRMER : l'onglet Databases de Pelican propose-t-il PostgreSQL ? (Administration → Database Hosts, vérification banc) -->

   <!-- CAPTURE C-051 -->

7. Start the server. Click Start and follow the console. The first start takes a few minutes: Agora downloads its database (about twenty MB) then itself. Do not click Stop or Kill in the meantime. You will see the steps scroll by: [1/6] Identité, [2/6] Licence, [3/6] Version, [4/6] Téléchargement, [5/6] Base de données, [6/6] Démarrage, then the ✓ Ready in … line. <!-- À CONFIRMER : durée réelle du premier démarrage avec la base intégrée (mesure banc Pelican, BASE-INTEGREE §6) -->

   <!-- CAPTURE C-052 -->

8. Open your site. In the server's Network tab, find the allocation: an IP address and a port, for example 203.0.113.20:3020 (an example address: yours will be different). Put http:// in front, in your browser: http://203.0.113.20:3020. The console also prints this address on the adresse line; if it shows a local address (10.… or 192.168.…), use the one from the Network tab.

   <!-- CAPTURE C-053 -->

9. Do the setup. The screen that opens guides you through three steps: see Do the getting-started setup.

   <!-- CAPTURE C-054 -->

You know it worked when… #

• The console shows ✓ base PostgreSQL intégrée prête, then ✓ schéma à jour, then ✓ Ready in ….
• Your browser shows the Mise en route (setup) screen.
• http://IP:PORT/api/health answers "ok": true and "db": "ok".

If it does not work #

I imported the wrong egg #

1. Stop the Agora server.
2. Import the Egg for Pelican (see step 3).
3. Change the server's egg so that it uses the right one, without deleting the server: its built-in database lives in its files, so deleting the server deletes the database too. <!-- À CONFIRMER : comment changer l'œuf d'un serveur existant sous Pelican (menu et libellés) -->
4. When no server uses the wrong egg any more, delete it from the list of eggs.

If you recreated the server anyway, it starts from an empty database: restore your latest Agora backup (see Backups and restore). A recreated server is a new installation: if the license says the seat is taken, read Free a license seat.

Going further #

What you must not change #

• The startup command: node /home/container/boot.mjs.
• The variables reserved for the panel administrator: the "Hub de licences" (AGORA_HUB, this is not your Hub but Agora's license server) and the "Site de l'amorçage" (AGORA_SITE). Also leave the "Secret d'authentification" (AUTH_SECRET) empty: Agora generates it on the first start.
• Nothing to change in Wings (the node program that carries out the panel's orders): Agora's console goes through the Agora server.

Where the data lives #

/home/container/
  boot.mjs      the bootstrap installed by the egg
  app/          the application (can be downloaded again)
  app/.data/    attachments, MDT files, .sql backups
  .agora/       installation identity, license lease, session secret,
                and your built-in database (pg folder)

The built-in database therefore lives inside the server's files. Losing .agora/ makes the installation look like a new machine. The panel's file copy (server backup, archive, SFTP) is not a database backup: it copies a database while it is running, which makes it inconsistent and often unusable on restore. Only Agora's backups count: see Backups and restore.

The txAdmin tab port #

The Port de l'onglet txAdmin variable (AGORA_TXADMIN_PORT, 40121 by default) serves the Server → txAdmin tab: put in it the number of a second allocation of the server (the first one serves the site). You can ignore it if you do not use that tab: see txAdmin in Agora.

Bringing your own PostgreSQL database (advanced option) #

Never required. If you already own a PostgreSQL server reachable from the container, you can paste its address in the Base de donnees variable, in the form postgresql://user:password@host:5432/database?schema=public. It then takes priority over the built-in database, which no longer starts. A few rules:

• It is PostgreSQL, not MySQL: the panel's Databases tab does not fit.
• Create the database and its user before starting; Agora creates everything else in it.
• If the password contains special characters (@, :, /, #…), replace them with their code (@ becomes %40).
• 203.0.113.20 is an example address: use yours.

<!-- CAPTURE C-307 -->

<!-- CAPTURE C-311 -->

To switch from one database to the other while keeping your data, see Move Agora to another machine. <!-- À CONFIRMER : œuf tout-en-un (claude/pg-integre), BASE-INTEGREE §5 : procédure intégrée ↔ externe non éprouvée sur le banc -->