How to Develop
This document will walk you through how to set up a local development environment for Agony Forge. By following this guide you'll be able to log into the demo MUD on your local machine and see how it works. You will also be able to make changes to the code and test them.
These instructions will not be sufficient by themselves to get a game on the internet for others to play. There are some additional steps to get there, such as creating an AWS hosted message queue, an AWS hosted DynamoDB, enabling HTTPS for a secure connection, and how to run the server on an actual server instead of your own computer. We'll tackle those things in different articles later on.
Our goal for this walkthrough is simple. We're going to set up the bare minimum resources required in AWS while keeping costs to an absolute minimum. At the end you will be able to log into your MUD that is running on your own computer using your Amazon account. Please be sure to check AWS pricing whenever you set up anything new, to avoid surprises. At the time of writing this, the costs for everything we'll need would be under a dollar a month in most regions.
Here is what we're going to set up:
- An OAuth application in GitHub.
- The configuration for Agony Forge demo MUD itself.
Here is what you'll need to have before we get started:
- An AWS account, and some familiarity with Cloud Formation.
- Git, and some familiarity with how to clone a project from GitHub.
- Docker, and some familiarity with how to use docker-compose.
- JDK 17 or better (I use Corretto, but other JVMs should work too).
The OAuth application is how you tell GitHub that your application exists and that it should help to authenticate users for you. You can create your application in GitHub by going into "Settings" (click your profile picture at the top right), then "Developer Settings", then "OAuth Apps".
Click the "New OAuth app" button to get started. There is a short form to fill out.
- You may choose any name you like for your application.
- Use
http://localhost:8080/for the Homepage URL. - Add a description if you want one.
- Use
http://localhost:8080/login/oauth2/code/githubfor the Authorization Callback URL. - Leave Enable Device Flow un-checked.
That's it!
On the next page you will get a client ID and you can generate a client Secret. Grab the values for both of those and keep them for the next step.
Finally! We just have a little configuration left to do locally before we can run the demo MUD.
First, make a copy of mud.EXAMPLE.env in the root directory of the project, and name the copy mud.env. This file sets environment variables that will be available to Spring inside its Docker container. mud.env is included in .gitignore to protect it from being pushed to GitHub but please be cautious because it will contain secrets that should never be included in version control.
The only section we need to worry about in mud.env is the bottom section. Everything else is all ready to go for local development. There are two sets of variables in the bottom section.
Variables beginning with SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GITHUB_...:
| Variable Name | Description |
|---|---|
| CLIENTID | This is the client ID you got from your GitHub OAuth app. |
| CLIENTSECRET | This is the client secret from your GitHub OAuth app. |
| REDIRECTURI | The default value is fine here. This is where the OAuth flow will redirect users to when they begin the login process. |
Time to see if everything worked! Build and run everything with:
$ ./gradlew clean build
$ docker-compose up
Pitest takes a long time to run, and you can skip it with ./gradlew clean build -x pitest.
If you don't want any tests at all, try ./gradlew clean build -x test -x pitest.
Once the logs stop scrolling, one of the last log messages should say something about a BrokerAvailabilityEvent. That probably means everything is up and running! Try visiting http://localhost:8080 in your browser. If everything is working, you should see a screen with a Login button.
When you click the button for the first time, you'll get redirected to Amazon where it will ask you to log in. Then it will ask you to authorize connecting your application to your account. Finally, it will redirect you back to the MUD where you should now see the main menu.
If you're making code changes and have to restart the MUD a lot, it is nice to not have to re-create your character every single time you log back in. You can keep the DynamoDB and RabbitMQ containers running and restart only the MUD by running this in a different terminal from where docker-compose is already running:
$ docker-compose up -d mud
You should be all set to make changes to the code at this point. Running the MUD in a production environment with other people is a longer topic but the overall idea remains the same. You need a database, a message queue, and the MUD running somewhere where they can run undisturbed for a long time and can be accessed from the public internet. AWS could work, or your own server. The details of how to do it are too long a topic for this article, but feel free to discuss it with us here in the GitHub discussions or on Discord.
Finally, if you run into any unexpected errors or other problems please feel free to open an issue or a discussion on GitHub. Try not to show any secrets in your post or if you take screenshots, and otherwise be as descriptive as you can. You are also welcome to join our Discord by clicking the badge at the top of the README.