This is the repository for Hangar, a plugin repository used for Paper, Velocity, and Waterfall plugins and similar software.
Hangar is loosely based off of Ore, created by the Sponge project, but rebuilt from the ground up using the Spring Boot Framework in Java for the backend and Nuxt (with UnoCSS) for the frontend. We would like to thank all Ore contributors. Without them, this project would never have been possible.
On top of our production instance at https://hangar.papermc.io/, we have a staging instance for testing purposes: https://hangar.papermc.dev/.
The project consists of 4 main parts
- Frontend (Vue.js under Nuxt with UnoCSS)
- Backend (Spring Boot)
- Database (PostgreSQL)
- User Management (HangarAuth; optional, see below)
There are two different environments that can be developed in, one using a fake user (without HangarAuth), or with HangarAuth. Most of the time you won't need to run Hangar with HangarAuth unless you are working with a feature that requires multiple user interactions.
Fake User environment (recommended, easy, no HangarAuth)
Fork the project and pull it in your IDE.
- Docker is required in order to run the PostgreSQL database
- Java 17 or higher
- pnpm
- git
To get the project running locally, you need to follow a few steps:
- Run
git submodule update --init
to initialize the HangarLib submodule. If you want to commit code to the lib repository (found infrontend/src/lib
) without cloning the repo separately, you also need to checkout a branch usingcd frontend/src/lib && git switch master
. - To get the dummy database up and running, move to the docker folder
cd docker
then rundocker-compose -f dev-db.yml up -d
(-d
as an optional parameter to run the containers in the background). Alternatively, if you are using IntelliJ you can press the green arrow in thedocker/dev-db.yml
file. - Run the Spring Boot application. You can do this in the CLI with
mvn spring-boot:run
, or if you're using IntelliJ, it is included in the run configurations. - Move to the
frontend
directory:cd ../frontend
. In that directory, runpnpm install
. This will install all the needed Node modules. - After the installation, run
pnpm run dev
in the frontend directory to initiate the build and launch. Changes you do to the frontend will be reloaded automatically. - After that, open http://localhost:3333, and if all went well, Hangar should be up and running.
- The Spring Boot configuration file that is used by this environment is located at
Hangar/src/main/resources/application.yml
. - The fake user settings are located in the application.yml file under
fake-user
. - Without HangarAuth, you should also disable sso under
use-sso
.
Fork this project and fork/clone HangarAuth. Ensure they are sibling directories in your file system.
Projects/
Hangar/
...
HangarAuth/
...
- Follow the installation instructions from the previous section and skip its notes (the fake-user and use-sso settings)
To get both Hangar and HangarAuth running locally:
- Setup HangarAuth
- See HangarAuth README
- Start HangarAuth's Docker services
- Create HangarAuth's Hydra client
- Move to Hangar's frontend directory
Hangar/frontend
. In that directory, runpnpm install
followed bypnpm run dev
. - Set up the Hangar client in Hydra (see HangarAuth README)
- Navigate to http://localhost:3333 and login.
- If using IntelliJ, you can view logs from each service in the Services tab (
ALT+8
). - The Spring Boot configuration file that is used by this environment is located at
Hangar/docker/hangar/application.yml
. - This setup requires the Hangar and HangarAuth projects to be sibling directories.
- To rebuild changes to Hangar, just rebuild in IntelliJ via
CTRL+F9
. - To rebuild HangarAuth, run
docker-compose up -d --build
inHangar/docker
.
Deployment happens via Docker, see the stack in the Docker folder. The Spring Boot configuration file used for deployment can be found at
docker/deployment/hangar-backend/application.yml
.
Hangar uses Crowdin for translations. If you want to contribute to translations, create a Crowdin account at https://hangar.crowdin.com/hangar and simply add new translations or comment/vote on existing translations. You can learn more about navigating the Crowdin UI here: https://support.crowdin.com/online-editor/.
crowdin pull --skip-untranslated-strings -b master -T <PAT>
You might want to set the env var TRANSLATION_MODE
to true in order to get warnings about untranslated strings.
Most of our current and future plans can be found in the Hangar Roadmap Project. Your best bet is joining the #development channel on the Hangar Discord to start discussing potential contributions and ideas. With Hanagr being such a massive project, any contributions are welcome!
Updating the frontend dependencies can be done best by running npx npm-check -u
and going through the changelogs. Note that package.json might contain hints
to which dependencies are broken.
If you want to have traces available locally, you can run zipkin via Docker like this:
docker run -d -p 9411:9411 openzipkin/zipkin
Then just enable it in the application.yml
under management.tracing
.
Hangar is licensed under the permissive MIT License.
A large part of the backend is based on Ore, also licensed under MIT:
Copyright (c) SpongePowered <https://www.spongepowered.org>
Copyright (c) contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.