The Broker is configured through environment variables or system properties, depending on your deployment type.
These settings are required regardless of your deployment method.
| Parameter | Description |
|---|---|
logback.configurationFile |
Path to the logback.xml logging configuration file (e.g., $CATALINA_BASE/conf/logback.xml) |
oslc.broker.host |
Your Broker public URL (e.g., https://your-server:your-port/) |
oslc.broker.oauth.cipher-key |
The key to encrypt OAuth secrets, when storing Friends and Consumers in the database. This is an arbitrary value that you must chose, similar to a password and specific to your deployment. Once a key is chosen and configured, it must never change, as this would break reading existing Friends and Consumers. |
jira-cloud.host |
Your Jira Cloud URL (e.g., https://company.atlassian.net/) |
jira-cloud.oauth.client.id |
OAuth Client ID from Atlassian Developer Console |
jira-cloud.oauth.client.secret |
OAuth Client Secret from Atlassian Developer Console |
jakarta.persistence.jdbc.url |
JDBC connection URL (e.g., jdbc:postgresql://database_server:5432/broker) |
jakarta.persistence.jdbc.user |
Database username |
jakarta.persistence.jdbc.password |
Database password |
If the database server is restarted or temporarily unreachable, the Broker's connection pool may retain stale connections. Without any validation, the Broker will recover database connection only after a first request fails or Tomcat itself is restarted, causing downtime.
The two optional parameters below instruct the connection pool to validate each connection with a lightweight SQL query before using it. If a connection is stale, it is discarded and a new one is established transparently, allowing the Broker to recover automatically in the background after a database restart.
| Parameter | Description |
|---|---|
hibernate.agroal.connectionValidator |
Defines how connections are validated. The value sql[SELECT 1] runs a ping request against
the database to confirm the connection is alive. The database will only return the constant 1.
|
hibernate.agroal.validationTimeout_m |
Maximum age of a connection (in minutes) before it is re-validated. A value of 1 means all
connections will be checked every minute.
|
oslc-connect-jira.xml template.
They add a small overhead (one SQL round-trip per connection checkout after the idle timeout), which is negligible in most environments.
If your database is highly stable and you prefer to avoid any extra overhead, you may keep these two parameters commented out.
In that case, the database connection will be discarded and recreated if a first request fail or if Tomcat is restarted.
The Broker uses a TCP connection pool when making HTTP requests to remote friended applications. By default, the maximum size of this pool
is 50 concurrent connections per remote host and 200 in total. When a new request is created, but all remote connections are
taken, the request is put on hold until a connection is free or its timeout expires (1 min). Changing the pool size defaults may
increase performance on environments with many friend applications or concurrent users. It can also prevent connection-timeout exception
messages from appearing in the log file. Be aware, however, that these numbers cannot be arbitrarily big; the maximum number of connections
is limited by Tomcat's maxThreads setting which defaults to 200. Set the context parameters below to change the defaults:
| Parameter | Description | Default Value |
|---|---|---|
com.sodius.oslc.client.http.connection-manager.max-per-route |
The maximum concurrent TCP connections per remote host. | 50 |
com.sodius.oslc.client.http.connection-manager.max-total |
The maximum concurrent TCP connections in total. | 200 |
For standalone Tomcat deployments, configuration is done via a Tomcat context file.
| Component | Location |
|---|---|
| Tomcat context configuration | $CATALINA_BASE/conf/Catalina/localhost/oslc-connect-jira.xml |
| Logging configuration (see logging page) | $CATALINA_BASE/conf/logback.xml |
| JVM settings | $CATALINA_BASE/bin/setenv.sh |
| SSL Configuration | $CATALINA_BASE/bin/server.xml |
| WAR file deployment | $CATALINA_BASE/webapps/ |
| Log files | ${user.home}/oslc-connect-jira-cloud/logs/ |
The Broker properties are configured in the Tomcat context file.
Edit configuration/oslc-connect-jira.xml and replace the placeholder values
for all context parameters, as documented in Application Configuration.
The setenv file configures JVM memory settings: -Xms512M -Xmx2048M
Remove application cache (if exists): $CATALINA_BASE/work/Catalina/localhost/oslc-connect-jira
Copy the WAR file in: $CATALINA_BASE/webapps/
Start Tomcat with: $CATALINA_BASE/bin/startup script
Stop Tomcat with: $CATALINA_BASE/bin/shutdown script
Those scripts can be launched as a service.
Access the application at: https://your-server:port/oslc-connect-jira/
Check the logs for any errors: ~/oslc-connect-jira-cloud/logs/broker.log