1+ ---
2+ title: Configuration - API Server
3+ category: Getting Started
4+ chapter: 1
5+ order: 7
6+ ---
7+ <!--
8+ GENERATED. DO NOT EDIT.
9+
10+ Generated with: {{ generateCommand }}
11+ -->
12+
13+ The central configuration file `application.properties` resides in the classpath of the WAR by default.
14+ This configuration file controls many performance tuning parameters but is most useful for defining
15+ optional external database sources, directory services (LDAP), and proxy settings.
16+
17+ For containerized deployments, the properties defined in the configuration file can also be specified
18+ as environment variables. All environment variables are upper case with periods (.) replaced with underscores (_).
19+ Refer to the [Docker instructions]({{ "{{ site.baseurl }}{% link _docs/getting-started/deploy-docker.md %}" }}) for
20+ configuration examples using environment variables.
21+
22+ Dependency-Track administrators are highly encouraged to create a copy of this file in the
23+ Dependency-Track data directory and customize it prior to deploying to production.
24+
25+
26+ > The default embedded H2 database is designed to quickly evaluate and experiment with Dependency-Track.
27+ > Do not use the embedded H2 database in production environments.
28+ >
29+ > See: [Database Support]({{ "{{ site.baseurl }}{% link _docs/getting-started/database-support.md %}" }}).
30+
31+
32+ To start Dependency-Track using custom configuration, add the system property
33+ `alpine.application.properties` when executing. For example:
34+
35+ ```bash
36+ -Dalpine.application.properties=~/.dependency-track/application.properties
37+ ```
38+
39+ ### Proxy Configuration
40+
41+ Proxy support can be configured in one of two ways, using the proxy settings defined
42+ in `application.properties` or through environment variables. By default, the system
43+ will attempt to read the `https_proxy`, `http_proxy` and `no_proxy` environment variables. If one
44+ of these are set, Dependency-Track will use them automatically.
45+
46+ `no_proxy` specifies URLs that should be excluded from proxying.
47+ This can be a comma-separated list of hostnames, domain names, or a mixture of both.
48+ If a port number is specified for a URL, only the requests with that port number to that URL will be excluded from proxying.
49+ `no_proxy` can also set to be a single asterisk ('*') to match all hosts.
50+
51+ Dependency-Track supports proxies that require BASIC, DIGEST, and NTLM authentication.
52+
53+ ### Logging Levels
54+
55+ Logging levels (INFO, WARN, ERROR, DEBUG, TRACE) can be specified by passing the level
56+ to the `dependencyTrack.logging.level` system property on startup. For example, the
57+ following command will start Dependency-Track (embedded) with DEBUG logging:
58+
59+ ```bash
60+ java -Xmx4G -DdependencyTrack.logging.level=DEBUG -jar dependency-track-embedded.war
61+ ```
62+
63+ For Docker deployments, simply set the `LOGGING_LEVEL` environment variable to one of
64+ INFO, WARN, ERROR, DEBUG, or TRACE.
65+
66+ ### Secret Key
67+
68+ Dependency-Track will encrypt certain confidential data (e.g. access tokens for external service providers) with AES256
69+ prior to storing it in the database. The secret key used for encrypting and decrypting will be automatically generated
70+ when Dependency-Track starts for the first time, and is placed in `<alpine.data.directory>/keys/secret.key`
71+ (`/data/.dependency-track/keys/secret.key` for containerized deployments).
72+
73+ Starting with Dependency-Track 4.7, it is possible to change the location of the secret key via the `alpine.secret.key.path`
74+ property. This makes it possible to use Kubernetes secrets for example, to mount secrets into the custom location.
75+
76+ Secret keys may be generated manually upfront instead of relying on Dependency-Track to do it. This can be achieved
77+ with OpenSSL like this:
78+
79+ ```shell
80+ openssl rand 32 > secret.key
81+ ```
82+
83+ > Note that the default key format has changed in version 4.7. While existing keys using the old format will continue
84+ > to work, keys for new instances will be generated in the new format. Old keys may be converted using the following
85+ > [JShell](https://docs.oracle.com/en/java/javase/17/jshell/introduction-jshell.html) script:
86+ > ```java
87+ > import java.io.ObjectInputStream;
88+ > import java.nio.file.Files;
89+ > import java.nio.file.Paths;
90+ > import javax.crypto.SecretKey;
91+ > String inputFilePath = System.getProperty("secret.key.input")
92+ > String outputFilePath = System.getProperty("secret.key.output");
93+ > SecretKey secretKey = null;
94+ > System.out.println("Reading old key from " + inputFilePath);
95+ > try (var fis = Files.newInputStream(Paths.get(inputFilePath));
96+ > var ois = new ObjectInputStream(fis)) {
97+ > secretKey = (SecretKey) ois.readObject();
98+ > }
99+ > System.out.println("Writing new key to " + outputFilePath);
100+ > try (var fos = Files.newOutputStream(Paths.get(outputFilePath))) {
101+ > fos.write(secretKey.getEncoded());
102+ > }
103+ > /exit
104+ > ```
105+ > Example execution:
106+ > ```shell
107+ > jshell -R"-Dsecret.key.input=$HOME/.dependency-track/keys/secret.key" -R"-Dsecret.key.output=secret.key.new" convert-key.jsh
108+ > ```
109+
110+ ---
111+
112+ ## Reference
113+
114+ <ul>
115+ {% for entry in propertiesByCategory %}
116+ <li><a href="#{{ entry.key | lower | replace({' ': '-'}) }}">{{ entry.key }}</a></li>
117+ {% endfor %}
118+ </ul>
119+
120+ {% for entry in propertiesByCategory %}
121+ ### {{ entry.key }}
122+
123+ {% for property in entry.value -%}
124+ #### {{ property.name }}
125+
126+ {{ property.description | replace({' ': '
127+ '}) }}
128+
129+ <table>
130+ <tbody style="border: 0">
131+ <tr>
132+ <th style="text-align: right">Required</th>
133+ <td style="border-width: 0">{{ property.required ? "Yes" : "No" }}</td>
134+ </tr>
135+ <tr>
136+ <th style="text-align: right">Type</th>
137+ <td style="border-width: 0">{{ property.type }}</td>
138+ </tr>
139+ {% if property.validValues -%}
140+ <tr>
141+ <th style="text-align: right">Valid Values</th>
142+ <td style="border-width: 0">{{ property.validValues }}</td>
143+ </tr>
144+ {% endif -%}
145+ <tr>
146+ <th style="text-align: right">Default</th>
147+ <td style="border-width: 0">{{ property.defaultValue }}</td>
148+ </tr>
149+ {% if property.example -%}
150+ <tr>
151+ <th style="text-align: right">Example</th>
152+ <td style="border-width: 0">{{ property.example }}</td>
153+ </tr>
154+ {% endif -%}
155+ <tr>
156+ <th style="text-align: right">ENV</th>
157+ <td style="border-width: 0">{{ property.env }}</td>
158+ </tr>
159+ </tbody>
160+ </table>
161+
162+ {% endfor %}
163+ {% endfor %}
0 commit comments