diff --git a/README.md b/README.md index ad70fcb7c..247a4139d 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ GEMP is a server written for Java 18, using MariaDB for a MySQL database instanc GEMP is divided into several modules which each handle a different aspect of the game, albeit for now they cannot be hosted separately (tho this is a future improvement we would like to make) ## gemp-lotr-async -This module manages the interface for the Javascript clients. Each JS operation that contacts the server will eventually terminate in a call to [communication.js](https://github.com/PlayersCouncil/gemp-lotr/blob/master/gemp-lotr/gemp-lotr-async/src/main/web/js/gemp-022/communication.js), which is ultimately just a wrapper for calls to [RootUriRequestHandler](https://github.com/PlayersCouncil/gemp-lotr/blob/master/gemp-lotr/gemp-lotr-async/src/main/java/com/gempukku/lotro/async/handler/RootUriRequestHandler.java), which routes each endpoint to the appropriate handler within gemp-lotr-async. From there the action could go anywhere depending on context. +This module manages the interface for the Javascript clients. Each JS operation that contacts the server will eventually terminate in a call to [communication.js](communication.js), which is ultimately just a wrapper for calls to [RootUriRequestHandler](RootUriRequestHandler.java), which routes each endpoint to the appropriate handler within gemp-lotr-async. From there the action could go anywhere depending on context. -gemp-lotr-async is also the home for the web portion of the project; everything in [/src/main/web/](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/gemp-lotr-async/src/main/web) is served as-is to the browser client, and the bulk of the Javascript can be found in [/js/gemp-022](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/gemp-lotr-async/src/main/web/js/gemp-022). /images contains icons, booster pack images, and other such resources. +gemp-lotr-async is also the home for the web portion of the project; everything in [/src/main/web/](gemp-lotr/gemp-lotr-async/src/main/web) is served as-is to the browser client, and the bulk of the Javascript can be found in [/js/gemp-022](gemp-lotr/gemp-lotr-async/src/main/web/js/gemp-022). /images contains icons, booster pack images, and other such resources. ## gemp-lotr-cards -This module contains the card definitions of both styles. Originally, cards were each written in Java, one class per card, and the majority of LOTR-TCG cards are still implemented in that format here, in [/src/main/java/com/gempukku/lotro/card](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/gemp-lotr-cards/src/main/java/com/gempukku/lotro/cards). +This module contains the card definitions of both styles. Originally, cards were each written in Java, one class per card, and the majority of LOTR-TCG cards are still implemented in that format here, in [/src/main/java/com/gempukku/lotro/cards](gemp-lotr/gemp-lotr-cards/src/main/java/com/gempukku/lotro/cards). However, in August 2019 work was underway to implement a "Second Edition" fan set, and requiring a server restart for every balance update and addition was proving to be too obnoxious, so the engine was extended to permit definitions of cards in JSON, which, as data, could simply be reloaded with an admin command rather than requiring a recompile. To date, all of the following card sets are implemented in JSON and not Java: @@ -63,14 +63,14 @@ The home for classes used in executing game rules and also in generating card ob The entry point for the server and the home for all database interaction, hall management, game running, chat, tournaments, and other services. -This is also the home for the unit tests for the server, which will fail compilation if they do not pass: [/src/test/java/com/gempukku/lotro](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/gemp-lotr-server/src/test/java/com/gempukku/lotro). Besides various service tests, there is a cards subfolder which contains a place to put unit tests for new cards (including errata). All PC V-cards and errata have a class for holding tests for that card, which are initially generated from the same spreadsheet that is used for generating the images and manually expanded as needed (see ketura for help on that). +This is also the home for the unit tests for the server, which will fail compilation if they do not pass: [/src/test/java/com/gempukku/lotro](gemp-lotr/gemp-lotr-server/src/test/java/com/gempukku/lotro). Besides various service tests, there is a cards subfolder which contains a place to put unit tests for new cards (including errata). All PC V-cards and errata have a class for holding tests for that card, which are initially generated from the same spreadsheet that is used for generating the images and manually expanded as needed (see ketura for help on that). Old card unit tests were scattershot and stored in the /at subfolder as needed. Do not add to this subfolder; instead use the cards subfolder mentioned above. # Hosting -GEMP includes tools for hosting within [Docker](https://docker-curriculum.com/), which makes setting up a local host a breeze (assuming the maintainers have kept the database scripts up-to-date). See the readme in the [/docker](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/docker) subfolder for more advanced details and instructions on the organization, but the following are basic instructions on how to start a local copy of GEMP. Make sure to follow the advanced instructions if hosting a production instance, as it will give steps for updating the default ports and credentials for db accounts and others. +GEMP includes tools for hosting within [Docker](https://docker-curriculum.com/), which makes setting up a local host a breeze (assuming the maintainers have kept the database scripts up-to-date). See the readme in the [/docker](https://github.com/PlayersCouncil/gemp-lotr/tree/master/gemp-lotr/docker) subfolder for more advanced details and instructions on the organization, but the following are basic instructions on how to start a local copy of GEMP. Make sure to follow the advanced instructions if hosting a production instance, as it will give steps for updating the default ports and credentials for db accounts and such. 1. Install Docker (Docker Desktop if on Windows). If you are on Windows, make sure that when you install it you check all boxes that have Docker behave like it's on Linux. @@ -78,41 +78,45 @@ GEMP includes tools for hosting within [Docker](https://docker-curriculum.com/), 3. Pull the git repository down to your host machine -4. Open a command line and navigate to gemp-lotr/gemp-lotr/docker. Run the following command: -``` -docker-compose up -d -``` - - You should see `Starting gemp_app....done` and `Starting gemp_db....done` at the very end. This process will take a while the first time you do it, and will be near instantaneous every time after. +4. Open a command line and navigate to gemp-lotr/gemp-lotr/docker. + * Run the command `docker-compose up -d` + * You should see `Starting gemp_app....done` and `Starting gemp_db....done` at the end. + * This process will take a while the first time you do it, and will be near instantaneous every time after. -5. The database should have automatically created the gemp databases that are needed. You can verify this by connecting to the database on your host machine with your DB manager of choice ([DBeaver](https://dbeaver.io/) is highly recommended). It is exposed on localhost:3307 (unless you changed this) and uses the user/pass of `gempuser`/`gemppassword` (unless you changed this). If you can see the `gemp_db` database with `league_participation` and other tables, you're golden. +5. The database should have automatically created the gemp databases that are needed. + * You can verify this by connecting to the database on your host machine with your DB manager of choice ([DBeaver](https://dbeaver.io/) is highly recommended). + * It is exposed on localhost:35001 (unless you changed this) and uses the user/pass of `gempuser`/`gemppassword` (unless you changed this). + * If you can see the `gemp_db` database with `league_participation` and other tables, you're golden. -6. Now we need to compile the gemp code. To do this, open a command line session in the gemp_app container (if using portainer.io, then log in, select your 'Local' endpoint, click the Containers tab on the left, click the `>_` icon next to gemp_app, then click the Connect button). +6. Now we need to compile the gemp code. + 1. Open a terminal inside the `gemp_app` container + * If using portainer.io, + * log in + * select your 'Local' endpoint + * click the Containers tab on the left + * click the `>_` icon next to gemp_app and click the Connect button + * If using Docker Desktop + * Open Docker Desktop + * Select the "Container" option in the left navbar + * expand the `gemp_1` container + * click the actiosn button and select `Open in Terminal` - - Navigate to the gemp codebase: -``` -cd etc/gemp-lotr -``` + 2. Navigate to the gemp codebase: `cd etc/gemp-lotr` - - Now tell Maven to compile the project: -``` -mvn install -``` - - This process will take upwards of 5-10 minutes. You should see a green "BUILD SUCCESS" when it is successfully done. In portainer.io or another rich command line context, you should see lots of red text if it failed. + 3. Now tell Maven to compile the project: `mvn install` + * This process will take upwards of 5-10 minutes. You should see a green "BUILD SUCCESS" when it is successfully done. In portainer.io or another rich command line context, you should see lots of red text if it failed. -7. Open [gemp-lotr/gemp-lotr/docker/docker-compose.yml](https://github.com/PlayersCouncil/gemp-lotr/blob/master/gemp-lotr/docker/docker-compose.yml) in your editor of choice, and uncomment line 35 (the "command" line). This will ensure that the container runs the gemp server every time it is started automatically. +7. Open [gemp-lotr/gemp-lotr/docker/docker-compose.yml](gemp-lotr/docker/docker-compose.yml) in your editor of choice, and uncomment [this line](https://github.com/PlayersCouncil/gemp-lotr/blob/master/gemp-lotr/docker/docker-compose.yml#L52). This will ensure that the container runs the GEMP server every time it is started automatically. -8. Navigate in a command line on your host machine (not in Docker) to gemp-lotr/gemp-lotr/docker and run the following commands: -``` -docker-compose down -docker-compose up -d -``` - - (This is how you restart GEMP any time that you need to incorporate changes to the Docker container. If you just need to reload freshly-compiled code, then restart the container directly via Docker or portainer.io.) +8. On your host machine cycle your docker container + * In a terminal navigate to `gemp-lotr/docker` + * Run `docker-compose down` + * After that completes run `docker-compose up -d` + * This is how you restart GEMP any time that you need to incorporate changes to the Docker container. If you just need to reload freshly-compiled code, then restart the container directly via Docker or portainer.io. 9. If all has gone as planned, you should now be able to navigate to your own personal instance of Gemp. Open your browser of choice and navigate to http://localhost:17001/gemp-lotr/ . - If you're presented with the home page, register a new user and log in. It's possible for the login page to present but login itself to fail if configured incorrectly, so don't celebrate until you see the (empty) lobby. If you get that far, then congrats, you now have a working local version of GEMP. +13. If you're presented with the home page, register a new user and log in. It's possible for the login page to present but login itself to fail if configured incorrectly, so don't celebrate until you see the (empty) lobby. If you get that far, then congrats, you now have a working local version of Gemp. By default, the above instructions will create 3 admin accounts: `asdf`, `qwer`, and `Librarian`, all with a password of `asdf`. Decks on the Librarian user will be automatically included in the Deck Library for all users, and the other accounts can be used for personal testing. Be sure to delete and/or change the credentials of these accounts if deploying to a production environment.