AlpineBits is an open standard to exchange touristic data.
This repository provides a library to implement AlpineBits server functionality. Use it to build your own standalone AlpineBits server, or integrate parts of it into your existing code base.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. Take a look at the Deployment section for notes on how to deploy the project on a live system.
To build the project, the following prerequisites must be met:
For a ready to use Docker environment with all prerequisites already installed and prepared, you can check out the Docker environment section.
Get a copy of the repository, e.g. by cloning it from the following location:
git clone https://github.com/idm-suedtirol/odh-alpinebits.gitChange directory:
cd odh-alpinebits/Build the project:
mvn clean installThe examples folder contains modules with pre-configured AlpineBits server
instances, that are easy to get up and running. The main point of the examples
is to demonstrate the usage of the library to create a functioning AlpineBits
server.
The handshaking example provides an AlpineBits server instance supporting
the so called Handshaking action.
Change to the handshaking directory (assuming you are in the projects root
folder):
cd examples/handshakingRun the following maven command:
mvn clean install cargo:runThis command starts a local Tomcat 8 instance using Cargo and deploys the example war file, generated during the installation (see Installing).
The deployment contains an AlpineBits server instance supporting the Handshaking action and a simple website to facilitate the communication with the server.
After Tomcat started, Open the website at http://localhost:8080/examples-handshaking/index.html.
The website provides a set of links and an output area. If you click on any of the links, the website will issue a request against the deployed AlpineBits server instance and display the results.
The housekeeping example provides an AlpineBits server instance supporting
the so called Housekeeping actions.
Change to the housekeeping directory (assuming you are in the projects root
folder):
cd examples/housekeepingRun the following maven command:
mvn clean install cargo:runThis command starts a local Tomcat 8 instance using Cargo and deploys the example war file, generated during the installation (see Installing).
The deployment contains an AlpineBits server instance supporting the Housekeeping actions and a simple website to facilitate the communication with the server.
After Tomcat started, Open the website at http://localhost:8080/examples-housekeeping/index.html.
The website provides a set of links and an output area. If you click on any of the links, the website will issue a request against the deployed AlpineBits server instance and display the results.
The inventory example provides an AlpineBits server instance supporting
the so called Inventory actions. A H2
instance is used for persistence (the database file is written with name
alpinebits_inventory to current user's HOME folder).
Change to the inventory directory (assuming you are in the projects root
folder):
cd examples/inventoryRun the following maven command:
mvn clean install cargo:runThis command starts a local Tomcat 8 instance using Cargo and deploys the example war file, generated during the installation (see Installing).
The deployment contains an AlpineBits server instance supporting the Inventory action. This example doesn't provide a UI, because its implementation would be rather demanding. At the moment, that effort is not justified.
You can use other tools like curl to perform requests against the running server.
The freerooms example provides an AlpineBits server instance supporting
the so called FreeRooms actions. A H2
instance is used for persistence (the database file is written with name
alpinebits_freerooms to current user's HOME folder).
Change to the freerooms directory (assuming you are in the projects root
folder):
cd examples/freeroomsRun the following maven command:
mvn clean install cargo:runThis command starts a local Tomcat 8 instance using Cargo and deploys the example war file, generated during the installation (see Installing).
The deployment contains an AlpineBits server instance supporting the FreeRooms action. This example doesn't provide a UI, because its implementation would be rather demanding. At the moment, that effort is not justified.
You can use other tools like curl to perform requests against the running server.
The code in this repository provides unit and integration tests.
The unit tests can be run with the following command:
mvn clean verifyTo run the unit and integration tests, use the following command, activating the
maven it profile:
mvn clean verify -P itYou can also integrate sonarqube to check the code quality. Run the following command:
mvn clean verify sonar:sonar -P it,reportTo generate the source JARs, use the sources maven profile, e.g. run the following command:
mvn clean install -P sources
The project provides a servlet as entry point to the AlpineBits server. If you want, to use it, the following additional prerequisites must be met:
- Servlet Container 3.x (e.g. Tomcat 8)
Using the provided examples as template (see Examples), you should be able to configure your AlpineBits server and to deploy the result as a war onto a servlet container.
For the project a Docker environment is already prepared and ready to use with all necessary prerequisites.
These Docker containers are the same as used by the continuous integration servers.
Install Docker (with Docker Compose) locally on your machine.
Before start working you have to start the Docker containers:
docker-compose up --build --detach
After finished working you can stop the Docker containers:
docker-compose stop
When the containers are running, you can execute any command inside the environment. Just replace the dots ... in the following example with the command you wish to execute:
docker-compose exec java /bin/bash -c "..."Some examples are:
docker-compose exec java /bin/bash -c "mvn clean install"
# or
docker-compose exec java /bin/bash -c "mvn clean verify"
# or
docker-compose exec java /bin/bash -c "mvn clean verify -P it"To check the code quality, you can run the following command and then visit the results at http://localhost:9000/:
docker-compose exec java /bin/bash -c "mvn clean verify sonar:sonar -Dsonar.host.url=http://sonar:9000 -P it,report"To server the example run the following command and then visit the website at http://localhost:8080/examples-housekeeping/index.html:
docker-compose exec java /bin/bash -c "cd examples/housekeeping && mvn cargo:run"For support, please contact Christian Gapp or IDM Südtirol - Alto Adige.
If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
This project uses SemVer for versioning. For the versions available, see the tags on this repository.
The code in this project is licensed under the Mozilla Public License 2.0 license. See the LICENSE file for more information.
- Christian Gapp - Initial work - gappc
This project is REUSE compliant, more information about the usage of REUSE in NOI Techpark repositories can be found here.
Since the CI for this project checks for REUSE compliance you might find it useful to use a pre-commit hook checking for REUSE compliance locally. The pre-commit-config file in the repository root is already configured to check for REUSE compliance with help of the pre-commit tool.
Install the tool by running:
pip install pre-commitThen install the pre-commit hook via the config file by running:
pre-commit install