This guide walks you through the initial setup phase of the infinitechess.org server on your machine. This only needs to be done once. Afterward, you will be able to run the website locally on your computer, write and modify code, suggesting changes to the github!
This is a team project!! Join the discord server to work with others, discuss how to improve the website, and ask questions! If you have trouble during this setup process, request help in the #help channel!
Summary of the setup process below for experienced users: Install VSCode and Node.js. Fork the repository and install the project dependencies via npm install. Now you can run npx nodemon to launch a live infinite chess server at https://localhost:3443. Optionally, you can also set up an email serivce now. You are now ready to test changes and contribute to the main project after reading the Navigation Guide! All these steps are explained in great detail below:
Let's check to make sure you have Git already installed. Open a command prompt (windows) or terminal (mac), and enter the following:
git version
If this outputs a version number, you have it installed, proceed to the next step! If it outputted unknown command, follow this guide to install it!
This guide will use VSCode, which is highly recommended, but you may use another code editor if you wish, as long as it is compatible with Node, npm, and has source control features. This guide will walk you through the process using VSCode.
Go here to download and install VSCode. Be sure you have Visual Studio Code, and not Visual Studio (they are different).
Go here to download and install Node. The easiest method is to click the "Prebuilt Installer" tab, download that, and run the installer.
Go to the repository's home page, then click "Fork"! You will need a github account.
On the next page, click "Create Fork".
Next, open VSCode, and click "Clone Git Repository..."
Click "Clone from GitHub".
Then click "Allow" to sign in with your github account, and, in the browser window that opened, click "Open Visual Studio Code.app".
The fork you just created should be at or near the top of the list, click on it! Be sure it has your github username on it! If it says "Infinite-Chess", don't click that one as it is the main repository, which you don't have write access to.
Choose a location on your machine to store the repository. Then when prompted whether to open the cloned repository, click "Open".
Inside the opened VSCode project, open a terminal window within it by going to Terminal > New Terminal.
Run the following command to auto-install all project dependancies:
npm install
To test run the server, and start it up from now on, enter the command:
npx nodemon
The first time you run this, you should see something like:
Subsequent times you start up the server will look like:
You should now be able to connect to the server through local host! Open a web browser and go to:
https://localhost:3443
It will warn us our connection is not private.
Click "Advanced", then "Proceed to localhost (unsafe)"!
Now you should now be able to browse the website and all it’s contents! Hooray!
Don't worry about the url bar telling you it's not secure. This can safely be ignored as you develop. It IS possible to get your computer to trust our newly created certificate, but it is not required, and these directions won’t include that. This one guy was able to figure it out though!
Now, stop the server by clicking in the VSCode terminal window to re-focus it, and hit Ctrl > C. If done correctly, you should be met with the following. This means the server has stopped.
Installing the ESLint VSCode extension will help your pull requests be approved quicker, by holding your code semantics to the standards of the project! ESLint will give you errors when you have undefined variables, missing semicolons, and other items, making it easier to catch bugs before runtime!
Go to the extensions tab, search for "eslint", click the one by "Microsoft", then Click "Install"!
Another highly recommended extension to install is "GitHub Pull Requests", which allows you to test-run other people's code suggestions on the repository, but it is not required.
While at this stage, you do have enough setup to be able to create new accounts while dev testing, you will not be able to receive account verification emails or password reset emails (planned) until we setup an email service. This step can optionally be skipped. If not setup, manual verification links are printed to the console when you create an account.
To do this, I recommend creating a brand new gmail account for this purpose. This account will be used to send emails on behalf of your locally running Infinite Chess server.
Note that gmail’s terms of service only allows automated email sending upon user-triggered events. Examples of okay emails to send are emails in response to a new account created, or a password reset request. An example of an against terms of service email would be a weekly newsletter. See gmail’s terms of service for more info.
After creating a new gmail account, turn on 2-Step Verification, this is required.
Next, go here where you will be able to create a new app password. If it tells you that App Passwords aren’t available for your account, you need to enable 2-Step Verification.
For the name field, it is unimportant, but you can enter Node.js. Then click “Create”.
It will generate a new app password, your screen should look like this, with a unique password:
Copy the 16-digit app password onto your clipboard. Next, go back to VSCode, and, in the root directory, open the .env file:
Paste your new app password next to the EMAIL_APP_PASSWORD variable. Then remove the spaces in the password.
Now, fill in the EMAIL_USERNAME variable with the email of the gmail account you just created the app password for.
DO NOT LET your app password be leaked!!! If that happens, bad actors will be able to hack into your gmail account. If you only keep your app password within the .env file, it will not be uploaded to github, this is because ".env" is specified within the .gitignore file, which specifies what files to skip over when uploading to github.
If your app password is ever leaked, or you suspect it might be, return to your app passwords page, and click the trash button to delete it. This invalidates that password so it can no longer be used in your account. Then you may generate a new app password.
At this stage, your .env file should be totally filled out, looking something like this:
You do have the option of changing what port the server is hosted on locally, by modifying the HTTPPORT_LOCAL and HTTPSPORT_LOCAL variables. If you do, be sure you modify the url you are visiting to access the web server, according to the port you set. By default, you visit https://localhost:3443, but if you modify the port, the 3443 here needs to be changed to match what you set it to.
Now upon creating a new account, you should see a message "Email is sent to member ExampleUsername!". If you see an error, or "Email environment variables not specified. Not sending email.", then it was setup incorrectly.
Note that you will only be able click "Verify Account" in the verification emails if you are on the same machine running the server, as the verification link contains localhost within it.
Let's move on to learn how to suggest changes to the repository! Or, skip right to the Conclusion.
After you have made some changes to the code, you can push those changes to your personal fork by going to the Source Control tab.
Only changes you "stage" will be sent to your fork! You can stage specific changes, or you can stage all your changes by clicking the "+" in the above image. Then click "Commit".
Enter a brief commit message, then click the checkmark in the top-right corner.
Now click "Sync Changes" back in the top-left!
If you now visit the fork you created on your own github account, the changes you made should now be found there as well!
Next, let's suggest this change to the official infinitechess.org repository by creating a "Pull Request"!
On the home page of the fork you created ON YOUR GITHUB account, click on "Pull Requests"
Now click "New pull request", followed by "Create pull request"! Your changes will be reviewed soon and either be accepted, rejected, or commented on!
Infinite Chess is a team project! Join the discord to discuss with the others how we should best go about things!
Next, read NAVIGATING.md for pointers on how to navigate the workspace, including where the game's code is located!