Installation

This topic will guide you through the installation of Axiomatics Policy DevOps (APD).

Prerequisites

Before you start, make sure you have the following requirements:

• Java 17 or later
• Git
• Internet access
  • See Network access for the domains that must be reachable
  • Without internet access, see Offline installation
• Axiomatics AWS credentials: your Axiomatics access key ID and Axiomatics secret access key
• An IDE, such as IntelliJ IDEA or Visual Studio Code (optional)
• Access Decision Service (ADS) license (optional)

Installation and configuration

Follow these steps to get started with the Axiomatics Policy DevOps:

1. Clone the APD project from GitHub.

   git clone https://github.com/axiomatics/axiomatics-policy-devops

2. Make the project your own:

   • In settings.gradle, replace the default project name my-alfa-project in rootProject.name.
   • Replace CODEOWNERS with the code owners of your team, or delete it.
   • Replace README.md with the description of your project.

3. Configure your Axiomatics AWS credentials, which give access to the Axiomatics Maven repository. APD reads them from the environment variables AXIOMATICS_ACCESS_KEY_ID and AXIOMATICS_SECRET_ACCESS_KEY, or from the Gradle properties with the same names.

   • On your machine, add them to the gradle.properties file in your home directory, ~/.gradle/gradle.properties:

     ~/.gradle/gradle.properties

     AXIOMATICS_ACCESS_KEY_ID=<access key id>
     AXIOMATICS_SECRET_ACCESS_KEY=<secret access key>

   • On a build server, set the environment variables from the secret store of your build server.

   warning

   Do not commit your credentials. Do not write them in the gradle.properties file of the project, which is in Git.

   note

   Your Axiomatics AWS credentials are provided as part of your Axiomatics license delivery. Contact Axiomatics support at support@axiomatics.com if you have not received them or if they have expired.

   If Gradle fails to download dependencies with a "Could not resolve" or "401 Unauthorized" error, verify that your credentials are correct and up to date.

4. If you have an ADS license, copy it to the license directory. Do not commit the license file unless your team decides to.

   ADS version	Filename
   ADS 2 and later	axiomatics_ADS.license
   ADS 1 (deprecated, will be removed in APD 27.1)	axiomatics_PDP.license

5. Verify the installation by running the tests of the sample project:

   ./gradlew test

   On Windows, run gradlew test. The output ends with BUILD SUCCESSFUL. To do the same in Visual Studio Code, see Quick start using VS Code.

Project structure

The APD project has the following structure:

📦axiomatics-policy-devops
 ┣ 📂build                                📖 Temporary directory with outputs
 ┣ 📂buildSrc                             ⛔ Internal scripts for bootstrapping the project
 ┣ 📂extra                                ⛔ Extra resources, replaced when APD is updated
 ┃ ┣ 📂exampleAds1Configuration           Dockerfile and deployment.yaml of the legacy ADS 1 (deprecated, removed in APD version 27.1)
 ┃ ┗ 📂exampleRequests                    Examples of sending requests to ADS using curl
 ┣ 📂gradle                               ⛔ Gradle internal files
 ┣ 📂license                              ✍ Your ADS license file
 ┣ 📂src
 ┃ ┣ 📂authorizationDomain                The authorization domain, see the tip below
 ┃ ┃ ┣ 📂alfaSpecifications               ✍ ALFA policies
 ┃ ┃ ┣ 📂attributeConnectors              ✍ Attribute connectors
 ┃ ┃ ┣ 📜attributeCache.yaml              ✍ Attribute cache settings
 ┃ ┃ ┣ 📜attributes.yaml                  ✍ Attribute dictionary
 ┃ ┃ ┣ 📜decisionParameters.yaml          ✍ ADS evaluation parameters
 ┃ ┃ ┣ 📜identity.yaml                    Optional: authorization domain identity, overrides the identity based on Git
 ┃ ┃ ┗ 📜metadata.yaml                    ✍ Authorization domain metadata
 ┃ ┣ 📂extra                              ✍ Files used by ADS or during tests: startService.sh, logback-custom.xml, keystores, truststores
 ┃ ┗ 📂test
 ┃   ┣ 📂java                             ✍ JUnit tests of your policies and attribute connectors
 ┃   ┗ 📂resources                        ✍ Test resources
 ┣ 📜AGENTS.md                            ⛔ Instructions for AI coding agents, replaced when APD is updated
 ┣ 📜AGENTS.local.md                      ✍ Optional: your own instructions for AI coding agents, kept when APD is updated
 ┣ 📜build.gradle                         ✍ Project build definition
 ┣ 📜CODEOWNERS                           ✍ Code owners of the repository: replace with your own
 ┣ 📜deployment.yaml                      ✍ ADS deployment descriptor
 ┣ 📜Dockerfile                           ✍ Dockerfile to build the ADS image
 ┣ 📜gradle.properties                    ✍ Gradle settings of the project, such as truststores. No credentials
 ┣ 📜gradlew                              ⛔ Gradle wrapper script (Linux and macOS)
 ┣ 📜gradlew.bat                          ⛔ Gradle wrapper script (Windows)
 ┣ 📜headers.json                         ✍ Optional HTTP headers sent when testing a remote ADS
 ┣ 📜README.md                            ✍ Description of your project: replace with your own
 ┗ 📜settings.gradle                      ✍ Project settings: only rootProject.name is yours, the rest is replaced when APD is updated

 ---

 Legend:
  ✍  File or directory that you'll likely modify or add to.
  📖  File or directory containing output (read-only).
  ⛔  File or directory that belongs to APD: do not modify, it is replaced when APD is updated.

tip

For a full reference of the authorization domain directory, read Authorization domain layout. For headers.json, see Test against a running ADS.

Upgrade

To upgrade APD to a later version, see Update.