Install on a host's Node.js server (agora.mjs)

In short. Many game hosts sell "Node.js" servers on which you cannot import an egg. No problem: you order one of those servers, you drop a single file, agora.mjs, and a small settings file, agora.env, that holds your license key. On start, Agora downloads and installs its database and itself: you have no database to prepare.

<!-- À CONFIRMER : toute cette procédure (voie « Option C ») n'a été testée chez aucun hébergeur réel : HUB-NODE-GENERIQUE.md, « Test à faire chez un hébergeur ». À éprouver sur le banc Pelican avec l'œuf « Node.js generic » avant publication (WORKFLOW phase 0 point 3) : démarrage, durée du premier lancement, mémoire. -->

Before you start #

• A "Node.js" server at a game host (it is often called that in the list of games or applications). It must run Node.js 22 or newer, on a 64-bit Intel or AMD processor (the case for almost every host), under Linux. If your host offers a panel where you can import an egg instead, Install on Pelican or Install on Pterodactyl are more direct; to tell your panel, see Tell Pelican and Pterodactyl apart.
• The server's resources: 2 GB of memory recommended (1 GB minimum) and at least 3 GB of disk (5 GB is more comfortable). A 512 MB plan is too tight: the server runs Agora and its database. <!-- À CONFIRMER : HUB-NODE-GENERIQUE.md annonce « 1 Go conseillé, 768 Mo minimum » ; l'œuf, lui, exige 1,5 Go (BASE-INTEGREE §3, mesure banc encore à faire). agora.mjs n'a aucun garde-fou mémoire. -->
• Your license key (it starts with AGORA-), on the Install on my panel page of your space on agorapanel.com (My account → Install on my panel): the "Your license key" section shows it on request. No key? Click Get my free trial key: see The 14-day free trial.
• The file manager of your host's panel (the file explorer in the browser): you use it to drop and create files.
• An outgoing HTTPS connection to the Internet from the server: Agora reaches agorapanel.com (license and download) and the npm registry (registry.npmjs.org, for the portable database).
• The words panel, Node.js, file manager and database are in the glossary; Agora's two databases are told apart in The two Agora databases.

Steps #

1. Order the Node.js server from your host, with the resources above.

   <!-- CAPTURE C-313 -->

2. Download agora.mjs. Save the file https://agorapanel.com/agora.mjs on your computer. It is a public file: it contains neither product code nor your key.

3. Drop it at the root of the server. In the panel's file manager, upload agora.mjs to the root (the starting folder, /home/container). Do not drop a package.json at the root.

   <!-- CAPTURE C-314 -->

4. Tell the server to start that file. In the server's Startup tab, set the "main file" variable (MAIN_FILE, sometimes written Main file) to agora.mjs. Leave the other variables empty.

   <!-- CAPTURE C-315 -->

5. Create the agora.env file. Still in the file manager, create at the root, next to agora.mjs, a new file named exactly agora.env, with these lines (replace the key with yours, no spaces or quotes):

   Copy

   AGORA_KEY=AGORA-XXXXX-XXXXX-XXXXX-XXXXX

   This kind of server offers no free variables: this file takes their place. It holds your key, keep it private. For the other possible settings, see "Going further".

   <!-- CAPTURE C-316 -->

6. Start the server. Click Start and follow the console. The first start takes a few minutes. Do not click Stop or Kill in the meantime. Each line starts with [agora-runtime and the time. You will see, in order: agora.env being read, the PostgreSQL database being downloaded (about twenty MB, checked against its fingerprint), its installation, your installation being registered, licence activée, Agora being downloaded, première installation : migrations…, démarrage d'Agora, then ✓ Ready in … and application prête. <!-- À CONFIRMER : durée réelle du premier démarrage et suite exacte des lignes de la console (non testé chez un hébergeur) -->

   <!-- CAPTURE C-317 -->

7. Open your site. Your host's panel shows your server's IP address and port (often in the Network tab or on the server's home page). Type them in your browser, preceded by http://, for example http://203.0.113.20:3020 (an example address: yours will be different).

8. Do the setup. The screen that opens guides you through three steps. It gives you the exact address to copy into Discord, in the form http://IP:PORT/api/auth/callback/discord: see Do the getting-started setup.

You know it worked when… #

• The console shows licence activée, then ✓ Ready in … and application prête.
• Your browser shows the Mise en route (setup) screen.
• http://IP:PORT/api/health answers "ok": true and "db": "ok".

The panel may show the server as "running" as soon as the process starts, well before the site is ready: rely on the application prête line. <!-- À CONFIRMER : comportement de l'indicateur d'état du panel avec l'œuf Node.js generic -->

If it does not work #

If nothing matches, open a ticket with the last page of the console: see Open a support ticket.

Going further #

The other agora.env settings #

Each line is written NAME=value. A line starting with # is a comment. If your host offers real environment variables, they take priority over the file.

# Required
AGORA_KEY=AGORA-XXXXX-XXXXX-XXXXX-XXXXX
# Optional: update channel (stable by default, beta reserved for the Pro tier)
AGORA_UPDATE_CHANNEL=stable
# Optional: your domain over HTTPS, if your host provides one
# AUTH_URL=https://forum.example.com

The file is tightened to owner-only read (0600 rights) at each start. The full list is in Environment variables.

HTTPS and public address #

Without a domain, your site opens at http://IP:PORT, which is enough to get started. The in-game tablet requires HTTPS on a public address: if your host offers an HTTPS sub-domain pointing to your port, or if you go through a Cloudflare tunnel, read Behind a proxy, then enter the address in Administration → Configuration → Agora resource, Public Hub address field.

Where the data lives #

/home/container/
  agora.mjs     the startup file
  agora.env     your settings, including your key
  data/         everything else: the database (pg folder), Agora's versions,
                the backups, the installation identity

Agora's backups (.sql files) are in data/backups, visible in the file manager. The host panel's file copy is not a database backup: it copies a database while it is running, which makes it inconsistent. Only Agora's backups count: see Backups and restore.

Updates #

They are done in one click in Administration → Agora, like the other routes: see One-click updates. The agora.mjs file itself does not update on its own, but it rarely changes: download it again only if the release notes ask for it.

Stopping cleanly #

Use Stop (not Kill) so the database shuts down cleanly. After a brutal stop, Agora recovers by itself on the next start.

Bringing your own PostgreSQL database (advanced option) #

Never required, unless the server cannot run the portable database. If you own a PostgreSQL server reachable from your server, add a line DATABASE_URL=postgresql://user:password@host:5432/database?schema=public to agora.env. It then takes priority over the built-in database. Create the database and its user before starting. <!-- À CONFIRMER : forme exacte de l'URL acceptée par agora.mjs pour une base externe, essai banc -->