This doc should be a 1 stop shop for getting your local development environment setup.
First thing you should know is how the file and folder structure is setup. This will greatly help you work with this repo.
Portaler Core is a monorepo that utilizes Yarn Workspaces to provide an easy way to manage this.
Individual applications can be found in the /packages folder. Portaler consists of 5 individual applications, all which can be worked on (mostly) independently and 3 or 4 shared services under /shared
- api-server
- The main API server
- bin-etl
- Checks for updates to the world.json file in broderickhyman/ao-bin-dumps
- Populates the database with initial information or updates information when the world.json changes
- discord-bot
- The discord bot that allows roles to be assigned to users
- Also contains the database migration files
- frontend
- The React frontend
Contained under the shared/* folder
- data-models
- A collection of commonly shared data functions and models for the database & redis
- logger
- An opinionated extension of Winston Logger that logs actions to the database
- types
- Just simply typescript type definitions shared across the different packages
- universal-utils
- A collection of common utilities that can be used in either the frontend or node servers
Currently, this project requires Yarn 1.x to be installed for using workspaces.
Yarn installation instructions
NPM released workspaces in v7.x, but this has not been tested. If you'd like to contribute to this section, feel free.
If you'd like to know about Workspaces, both of the above links should provide enough explanation.
To run everything in Portaler, you're going to need to understand environment files or .env files and you'll need to know what the different keys you'll need are and where to get them.
An .env file is simply contains variables that are usually machine wide or in secure stores when in production. Things such as secrets or API keys. For dev we usually use .env files for ease of use. There isn't anything fancy here, there is no .env.production or .env.development like you see in some projects, there are simply .env.example files which are example setups meant to be checked in and .env files that are ignored in the .gitignore.
Each package will or should have an .env.example file. The TL;DR is to simply copy this file to .env and start filling in the blanks.
cp .env.example .envThis is only needed for the bin-etl package, but if you're trying to use the API then you'll need to run this at least once to populate the database, or manually fill it in yourself.
Creating a Personal Access Token is extremely easy. The bin-etl is reading from a public repo, so it needs NO scopes.
Click the screenshot below to see an example:
Once created, this token goes in your /packages/bin-etl/.env file as the variable ACCESS_TOKEN=.
ie:
WORLD_FILE_URL=https://raw.githubusercontent.com/broderickhyman/ao-bin-dumps/master/cluster/world.json
ACCESS_TOKEN=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The Discord stuff is by far the most intense. It's needed in the API and Discord Bot, and hopefully in the future Frontend when we have self-signup working (issues #64 and #65).
Since this process is a little more involved, it has it's own tutorial here:
* Note: If you're just working on the frontend you can simply configure the .env variables:
In /packages/api/.env:
# used for dev only
FRONTEND_PORT=3000
DISABLE_AUTH=trueIn /packages/frontend/.env:
# Dev only
REACT_APP_AUTH=http://localhost:3000
REACT_APP_DISABLE_AUTH=trueWith the exception of installing new libraries, it's better and easier to work from the root directory. Working from individual directories can sometimes get weird.
External libraries are installed in their individual There are commands that allow you to install libraries from root, but they are verbose and annoying. Most people just cd into the correct directory and install normally. Yarn Workspaces will take care of the rest. The few packages installed at root are for development purposes only.
Be sure to check out the "scripts": {} we have provided in the root package.json file, that will make your life easier.
There are a number of scripts that can be run from the root of the project that make life a little easier. Before running them, you need to install project dependencies, run the following from your project root:
yarn install
To run the following commands, from the root of the project simply type:
yarn <command>build:data- Builds the shared/data-models packagebuild:logger- Builds the shared/logger packagebuild:utils- Builds the shared/universal-utils packagebuild:shared- Builds both of the above concurrentlydev:api- Starts the api-server in development modedev:bot- Starts the discord-bot in development modedev:front- Starts the frontend in development modedev:homepage- Starts the Gatsby homepage in development modedev:binetl- Starts the bin-etl in development modebuild:api- Builds the api-server for productionbuild:bot- Builds the discord-bot for productionbuild:binetl- Builds the bin-etl for productionbuild:front- Builds the frontend for productionbuild:homepage- Builds the homepage for productionstart:api- Starts the api-server from production mode (must be built first)start:bot- Starts the discord-bot from production mode (must be built first)start:binetl- Starts the bin-elt from production most (must be built first)clean:shared- Deletes the node_modules folder for all the shared/* modulesclean:packages- Deletes the node_modules folder for all the packages/* modulesclean- Deletes all node_modules folders everywhereclean:out- Deletes all built projectsclean:all- Deletes all built projects & node_moduleslint- Provides a lint output of all the files in the entire projectlint:fix- Attempts to lint and fix all the files in the entire project