Installation and Setup

Note

These instructions are for installing Alter Ego using Docker. If you wish to not use Docker, please refer to the node installation instructions.

Installation of Alter Ego is rather complicated, but is made significantly easier with Docker. This page will explain the process in detail.

Caution

Do not host Alter Ego for anyone you don’t trust. For more information on why you shouldn’t, see the warning for Flag value scripts.

Step 0: System Requirements

Note

The requirements below are for Linux servers. For system requirements for Windows and Mac, refer to their respective Docker Desktop documentation.

Although Alter Ego can run on any system that can run Docker, running it on a Linux VPS is recommended, as performance on Windows and Mac are inferior and can be significantly slower. For instance, the Windows version of Docker relies on virtualization, and therefore suffers a large performance penalty. Some good VPS providers include Hetzner, DigitalOcean, and Linode.

Step 1: Download Alter Ego

First, you need to download Alter Ego itself. Go to the GitHub Releases page and find the latest release.

There, you will see something like this.

Windows, Linux, Mac Desktop

From this page, download the archive Alter-Ego-[VERSION].tar.gz. Use your favorite archive utility to open the archive (e.g. 7zip, GNOME Archive Manager, PeaZip), and extract the contents into your folder of choice.

Linux Terminal

Use wget to download the archive straight from the terminal. The following is an example (replace VERSION with the version you want to download).

wget https://github.com/MsVBLANK/Alter-Ego/releases/download/[VERSION]/Alter-Ego-[VERSION].tar.gz

Unarchive the Alter-Ego folder by running this command (replace VERSION with the version number).

tar -xzvf Alter-Ego-[VERSION].tar.gz

Step 2: Install Docker

If you already have Docker installed, you can skip this step.

Docker is a container management platform that allows users to run applications on their machines regardless of operating system or dependencies. It has very low performance overhead, and provides isolation that improves security.

Although Alter Ego can be installed bare-metal (i.e. without Docker), this is not recommended unless you plan to work on the source code as a developer.

Linux

To install Docker on your Linux system, refer to the link below:

https://docs.docker.com/engine/install/

Most cloud/VPS providers offer a Docker installation image when you create your VM (e.g. Hetzner).

This saves you time and effort from installing Docker yourself, and is highly recommended for new users.

Windows

To install Docker on your Windows system, refer to the link below:

https://docs.docker.com/desktop/install/windows-install/

You can also consult this YouTube tutorial for a step-by-step guide.

Mac

To install Docker on your Mac system, refer to the link below:

https://docs.docker.com/desktop/install/mac-install/

You can also consult this YouTube tutorial for a step-by-step guide.

Step 3: Create a Discord bot

Now that you have Alter Ego installed, you’ll need to create a new Discord bot to bind its functionality to. Navigate to the Discord Developer Portal, and once you log in to your Discord account, create a new application. This example will use an application called “Alter Ego”, but you can call it whatever you like. Once you create the application, you’ll be taken to a page that looks like this:

You can ignore this for now. Navigate to the Installation tab on the left-hand side. This will bring you to this page:

Under “Installation Contexts”, uncheck “User Install”, and make sure “Guild Install” is checked. In the dropdown under “Install Link”, select “None”. You don’t want other people to be able to install your bot to their servers, so there’s no need to create a public installation URL.

Now navigate over to the Bot tab on the left-hand side. This will bring you to this page:

On this page, you can change the bot’s name, set its profile picture, upload its banner image, and a few other things. Take note of the “Reset Token” button; you’ll need to press it later, but you can ignore it for now.

Scroll down a bit, and you’ll find some settings. First, under “Authorization Flow”:

• Disable the “Public Bot” setting.
  • Alter Ego can only be in one server, so this will prevent other people from inviting it to their servers.
• Disable the “Requires OAuth2 Code Grant” setting.

Next, you’ll find more settings under “Privileged Gateway Intents”:

• Enable the “Presence Intent” setting.
• Enable the “Server Members Intent” setting.
• Enable the “Message Content Intent” setting.

Without all of these set according to these instructions, Alter Ego will not function properly. If you’ve done everything right, your settings will look like this:

Step 4: Create a Discord server

Before you can get Alter Ego up and running, you’ll have to create a Discord server. You can call it whatever you like, but once it’s made, you’ll have to set a number of things up.

The easiest way to create a server is using this template, which will add all of the requisite roles and channels for you. If you want to set those up manually, refer to this page.

Enable Developer Mode

You’ll have to enable Developer Mode for your account for the next few steps. To do this, navigate to your User Settings in Discord. Open the Developer tab near the very bottom. You’ll see a switch labeled Developer Mode. Turn it on if it’s not already enabled.

Step 5: Invite your bot to the server

Back on the Discord Developer Portal, click on the OAuth2 tab on the left-hand side. Scroll down to the “OAuth2 URL Generator” section:

Under “Scopes”, Check bot, then in the “Bot Permissions” section that appears below it, check Administrator. You should have something that looks like this:

Finally, there will be two text boxes underneath the “Permissions” section:

Under the “Integration Type”, dropdown, select “Guild Install”. Then, copy the URL in the “Generated URL” box, send it to a Discord channel in the server you just made (ideally to a channel that only you have access to), and click on it. It should display a menu that looks like this:

Make sure the server you just made is the one that’s selected in the drop down, then click Continue. Make sure Administrator is checked, and confirm by clicking Authorize.

With that, your bot will join your server! However, it doesn’t do anything at the moment. You still need to do a few things.

Step 6: Create a spreadsheet

Next, you will need to create a spreadsheet for Alter Ego to use. For more information, see the article on spreadsheets.

Step 7: Enable the Google Sheets API

In order for Alter Ego to work properly, you will need to create a new Google APIs project. The easiest way to do that is to navigate to the Enable Google Workspace APIs page and click the Enable Sheets API button near the bottom.

That should bring you to a page that looks like this:

Create a project. You can call it anything you want. In the prompts that follow, confirm that you want to enable the Google Sheets API. If you did it right, you’ll be shown a message that says “You have successfully enabled Google Sheets API.”

Step 8: Create a service account

In order to allow Alter Ego to read and write to the spreadsheet, you’ll need to create a service account for it to use. To do that, open the navigation menu in the top left corner and navigate to the Credentials tab under APIs & Services, like so:

On the next page, click the link that says Manage service accounts:

On the next page, click Create service account. You should be brought to a page like this:

For the name, enter the bot’s name; in this case, it’s Alter Ego. You can set its ID if you want, or just accept the one it generates. For the description, enter whatever you like. Click Create and continue.

In the Permissions menu, grant it the “Owner” role. You can skip step 3. Once you’re done, you’ll be returned to the Service accounts page.

Once your service account is made, you should see it under the service accounts list. There will be a meatball menu under the Actions column for it. Click on that, and select Manage keys. You’ll be taken to this page:

Click the Add Key button and select Create new key. Make sure the key type is JSON, then click Create. This will download a file to your computer. Don’t touch that just yet - there’s one thing to do first. Return to the Service Accounts page.

Step 9: Share the spreadsheet

On the Service Accounts page, you should now see the service account you just created. Copy its email address, then head over to the spreadsheet you made earlier.

On the spreadsheet, press the Share button. Paste the service account’s email address into the dialog box and make sure to give it permission to edit the spreadsheet. You can also do the same with any other moderators you have, if you haven’t done so already. Once you’ve done that, you nearly have everything you need.

Caution

Do not grant write access to the spreadsheet to any users that you don’t fully trust.

Step 10: Edit .env file

The .env file is used to change all settings for Alter Ego. Before running Alter Ego, you must change several values here.

First, open the Alter-Ego folder that you downloaded. Then, make a copy of .env.example and name it .env (note you may have to set your file browser to show hidden files). On Linux, use these commands.

cd Alter-Ego
cp .env.example .env

Open the .env file in a text editor. You should see something like this:

# This is an example of an environment file for docker compose.
#
# '#' has been used to comment out any variables that do not need
# to be changed from default. Remove '#' to set them if you want
# to use something other than the default value.
#
# Environment variables should be enclosed in single quotes, and
# should follow the data type next to it (e.g. String).
# For instance: DEBUG_MODE='true'

# Time Zone
# See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
# for a complete list of timezones.
TZ='America/New_York'

# Credentials
DISCORD_TOKEN=                                # String. Token of discord bot
G_PROJECT_ID=                                 # String. Google project ID
G_PRIVATE_KEY_ID=                             # String. Google private key ID
G_PRIVATE_KEY=                                # String. Google private key
G_CLIENT_EMAIL=                               # String. Google client email
G_CLIENT_ID=                                  # String. Google client id
G_CLIENT_X509_CERT_URL=                       # String. Google cert url

# Settings
SPREADSHEET_ID=                               # String. ID of spreadsheet
...
(file continues on)

Setting Time Zone

Before running Alter Ego, you should set the time zone for your container, so that events in the game sync up to your location.

Edit the TZ line so that it matches the time zone where the game occurs in. For instance, if you want to set the timezone to London, you would change the line to TZ='Europe/London'. For a complete list of timezones, refer to this Wikipedia article.

Setting Credentials

Navigate back to the Discord Developer Portal once again and find the application you created earlier. Open the Bot tab. Under Token, click Reset Token. You may be asked to authenticate with 2FA before proceeding. Once the token has been created, click Copy. Paste it inside the single quotes after DISCORD_TOKEN= in your .env file.

Caution

This token must not be shared with anyone, as it grants full access to your bot’s account.

Next, open the file you downloaded after creating the service account in any text editor. The file should look something like this:

{
    "type": "service_account",
    "project_id": "(CONFIDENTIAL)",
    "private_key_id": "(CONFIDENTIAL)",
    "private_key": "(CONFIDENTIAL)",
    "client_email": "(CONFIDENTIAL)",
    "client_id": "(CONFIDENTIAL)",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "(CONFIDENTIAL)",
    "universe_domain": "googleapis.com"
}

Caution

Almost all of the data in this file is confidential. Don’t share it with a single person, and make absolutely sure not to put it online somehow.

Next, add the Google service account credentials to your .env file. Copy each corresponding value in the Google credentials file into your .env file. For instance, copy project_id into PROJECT_ID=. Replace the double quotes in the original file with single quotes. Don’t worry about any values that aren’t in the .env file, you won’t need them.

If you did everything right, the credentials section should look like this:

...
# Credentials
DISCORD_TOKEN='(CONFIDENTIAL)'                      # String. Token of discord bot
G_PROJECT_ID='(CONFIDENTIAL)'                       # String. Google project ID
G_PRIVATE_KEY_ID='(CONFIDENTIAL)'                   # String. Google private key ID
G_PRIVATE_KEY='(CONFIDENTIAL)'                      # String. Google private key
G_CLIENT_EMAIL='(CONFIDENTIAL)'                     # String. Google client email
G_CLIENT_ID='(CONFIDENTIAL)'                        # String. Google client id
G_CLIENT_X509_CERT_URL='(CONFIDENTIAL)'             # String. Google cert url
...

Setting Spreadsheet ID

Finally, you must set the spreadsheet ID. A Google Sheets URL contains two IDs. The first is the ID of the entire spreadsheet itself. The second is the ID of the individual sheet currently open in the spreadsheet. You can retrieve the ID of either by copying them from the URL. The format is as follows:

https://docs.google.com/spreadsheets/d/(entire spreadsheet ID)/edit#gid=(individual sheet ID)

Copy the ID for the entire spreadsheet and paste it in single quotes after SPREADSHEET_ID=. For instance.

SPREADSHEET_ID='1234567890'

(Optional) Fill out other settings

If you wish to change other settings other than the ones outlined above, you can edit their entries in the .env file. Remember to uncomment (i.e. remove the # before the line) for them to go into effect. For more information, see the article on settings.

Step 11: Run Alter Ego

Finally, you can run Alter Ego. First, make sure that you are in the directory where Alter Ego is installed.

In a terminal, run:

docker compose up -d

If you did everything right, you’ll see something like this:

If you run the command docker compose logs, you should see this:

alterego  | Alter Ego (VERSION) (commit (COMMIT))
alterego  |
alterego  | Writing configuration files...
alterego  | Done.
alterego  |
alterego  | Starting Alter Ego...
alterego  | AlterEgo-test is online on 1 server.
alterego  | Loaded all commands.

Congratulations! If everything went well, you can now use Alter Ego. Good luck!

Updating Alter Ego

To update Alter Ego, first take the container down with this command.

docker compose down

Next, open docker-compose.yml. You should see something like this.

services:
    alterego:
        image: ghcr.io/msvblank/alter-ego:1.10.1
        container_name: alterego
        env_file:
            - .env
        volumes:
            - data:/home/node/app/Configs
        restart: unless-stopped

volumes:
    data:

Then, change the image: line so that it corresponds to the new version of Alter Ego. For instance, change 1.10.1 to 2.0.0. The line should now read something like this.

image: ghcr.io/msvblank/alter-ego:2.0.0

Save the file and quit your text editor.

Next, pull the new update using the following command:

docker compose pull

Finally, simply start the container again and Docker will automatically update Alter Ego for you.

docker compose up -d

Docker Commands

To view the status of your container, run:

docker ps

To view the logs of Alter Ego, run while in the same directory as Alter Ego:

docker compose logs

To stop the container, run:

docker compose stop

To start the container after stopping it, run:

docker compose start

To restart the container, run:

docker compose restart

For a full reference to Docker Compose, refer to the official documentation.