Guilded: set up your own guild

Prefer to add the existing bot without hosting? Join the hosted pilot. KCaron must approve your server before it works. After approval, start at /setup start; you do not need the infrastructure steps below.

First time hosting anything? Use the illustrated beginner walkthrough for Discord and Oracle signup links, screenshots, commands and success checks. This page is the shorter technical reference.

One owner hosts the Discord bot and database; members install the addon and use the online companion by default. The Windows app is optional for automatic sync, especially useful for leaders and officers. Guilded 6.0.0 is the full Release: use a published release's matching downloads and source, and read its known limitations. Fresh-guild and non-developer-PC acceptance tests are still pending for 6.0.

Start with the 30-minute checklist. That is a target with hosting, database and DNS ready, not a measured promise for a first-time cloud signup.

Already running Guilded? Follow the backup and update gates in V5_0_RELEASE_HANDOFF.md. This guide is for a new guild.

Before you begin

You need permission to manage your Discord server, your own Discord application, a PostgreSQL database, and one machine to keep the bot running. Members on other PCs need a reachable HTTPS bot address. The packaged addon/companion do not include hosting or a shared public bot service.

Record these non-secret details as you go:

Keep the Discord bot token and database connection string in .env.local on the bot host. Members use their own pairing codes; they never need those host secrets.

1. Create and invite your Discord application

1. In the Discord Developer Portal, create your application. Record its application ID and obtain its bot token.
2. Under Bot → Privileged Gateway Intents, enable Server Members Intent. Guilded requires it. Message Content Intent is optional for the answer channel and can stay off during initial setup.
3. Configure Guild Install with scopes bot and applications.commands, then open the generated installation link and select your server. See Discord's installation guide.
4. Grant View Channels, Send Messages, Send Messages in Threads, Create Public Threads, Manage Threads, Embed Links, Attach Files, Read Message History, Manage Channels, Manage Roles and Create Events. Grant Manage Messages for message/pin maintenance and moderation; Connect for events in voice channels. Enable additional moderation permissions only for the actions you will use.
5. Place the bot's role above every role it needs to assign or manage, including member, applicant and game roles. Check channel-specific permission overrides.
6. Enable Discord Settings → Advanced → Developer Mode, then right-click your server and Copy Server ID.

Checkpoint: the correct bot appears in your server. It stays offline until its service starts. Guilded uses a gateway connection; its setup does not require an Interactions Endpoint URL or a user-account token.

2. Prepare the bot host

Use Node.js 24 LTS, the release build/CI baseline, from Node.js downloads. Use PostgreSQL 16 or later; the database must be reachable by the host. You may use an existing PostgreSQL service or a provider such as Neon; check your provider's current limits and costs.

Get the source for your selected release from GitHub Releases, using the source ZIP attached to that release. If your officer supplies an unpublished beta, use its matching source commit and downloads; do not assume the latest default branch matches them. Keep the source commit with your installation record. Create .env.local from .env.example and fill these fields locally; do not paste secrets into chat or an issue:

For the recommended Ubuntu installation, the server installer below copies the example for you. Edit /opt/guilded/.env.local there after installation; you do not need Node.js on your Windows PC or to fill two configuration files.

For a new source installation, npm ci installs the locked dependencies, npm run companion:build builds the online companion, and npm run db:update applies migrations and generates the database client. Existing databases need a verified backup and ledger preflight before an update. Never reset a database to get past a migration error.

The Ubuntu installer performs dependency installation and the web build, and the service applies migrations on its first start. Do not repeat those commands on your Windows PC. Run npm run setup:check on the host after entering the four required values. Blank optional fields are supported. The check is offline: it does not validate credentials with Discord or connect to your database.

Hosting for the whole guild

The included Ubuntu/systemd/Caddy deployment is described in DEPLOY_ORACLE.md. Use your own hostname, server, SSH access and database. The setup script installs Node 24 when Node is missing or older; older 5.0 source bundles may still default to Node 22. It writes /etc/caddy/Caddyfile, so use a dedicated host or have the host administrator integrate the configuration.

Point your hostname to the server and allow HTTPS through its cloud and OS firewalls. Caddy proxies the local API; members should not connect to port 8787 directly. The host's service is the single bot process. Stop any prior instance before moving that bot token to another host.

Do not run the repository's redeploy-oracle.bat unmodified for another guild: it targets the maintainer's existing server. Use the server-side update procedure on your own host, after the release checks and backup gates.

Checkpoint: https://your-host/health returns ok: true with the intended version/protocol, and /report ping responds in your Discord server. The online companion opens at https://your-host/companion/. A working Discord bot alone does not prove the HTTPS companion endpoint works from members' PCs.

3. Configure Discord with the wizard

As a server administrator, run /setup start. Select English or Français. For each channel, select one you already have or use Create the missing ones for me. Set member/leadership roles and the desired onboarding/rules options. Use Update bot messages, then /setup start status:true to review anything missing. Optional features can remain disabled.

Run /core setup for each raid roster. Select the loot method and decide whether points use the guild pool or a separate core pool. Give a priority core item prices before testing an award. /core edit changes the roster and rules.

Choose whether officers review uploads with /import apply, or enable automatic guild import with /config auto-import. Personal member uploads remain restricted to their own characters; do not give everyone officer access for sync.

Checkpoint: test with an ordinary member account: it sees the intended public roster/signup channels and cannot see officer-only channels or use officer actions.

4. Connect one officer and one member

Follow the member install guide on both PCs. Give each person your bot address and server ID; each obtains their own /character pair code. New desktop installs ask for Your guild's bot address beside the pairing fields. Older 5.0 builds have a prefilled Quebec Gold address: replace it in Advanced preferences before pairing with a different guild's bot. Upgrades preserve saved addresses and pairing credentials.

Confirm all of these before inviting the whole guild:

• The officer and member both upload successfully after /reload and see their own linked character. Only the officer can upload guild ledger changes.
• Fresh standings return through the companion and appear after another reload.
• A test raid signup uses the intended character/core, and its member can see it.
• Recipes appear after opening a crafting profession and syncing; members do not have to run a recipe command to enable collection.
• The companion recovers when the bot becomes reachable again after a planned interruption, without duplicating imported entries.

Use a test server/core and test data for award and permission experiments. Do not alter live balances just to test the install. Keep meaningful backup/restore and real-raid checks in your release record.

5. Give members one pinned message

Fill every placeholder before posting this in your own server:

Install Guilded for our guild
Addon: <release download link>
Optional Windows companion (automatic sync): <matching installer download link>
Setup guide: <link to MEMBER_INSTALL.md for this release>
Our Discord server ID: <copy exact ID>
Our bot address: <https://our-host/api/v1/addon-imports>
Online companion (default): <https://our-host/companion/>
Install the addon in your actual WoW client, log in, then /reload.
Open our online companion link; desktop users set our bot address before connecting.
Use /character pair here in Discord to get your own private code.
Need help? Contact <officer>; share the error or support summary, never your code.

If a checkpoint fails

For guided help, copy an AI setup prompt and attach this guide and the release README. Optional in-server AI answers are a separate feature; they are not required to install Guilded.