Skip to content

Latest commit

 

History

History
135 lines (100 loc) · 5.14 KB

README_installationguide.md

File metadata and controls

135 lines (100 loc) · 5.14 KB

Installation and Configuration Guide

This guide provides step-by-step instructions for installing, configuring, building, and deploying the Webex Contact Center DB Connector.

1. Prerequisites

  • Java Development Kit (JDK): Version 24 or higher.
  • Maven: The project includes a Maven wrapper (mvnw), so a local Maven installation is not strictly required, but internet access is needed to download dependencies.
  • Webex Integration: You must have a Webex Integration created in the Webex Developer Portal.

2. Configuration

2.1. Application Properties

The main configuration file is located at src/main/resources/application.properties.

Required Updates: You must update the Webex OAuth2 credentials with your specific integration details.

# Webex OAuth2 Configuration
spring.security.oauth2.client.registration.webex.client-id=YOUR_CLIENT_ID_HERE
spring.security.oauth2.client.registration.webex.client-secret=YOUR_CLIENT_SECRET_HERE

Optional Database Configuration: By default, the application uses an embedded H2 database stored in the ./data directory relative to where the application is run.

spring.datasource.url=jdbc:h2:file:./data/dbconnector
spring.datasource.username=sa
spring.datasource.password=password

2.2. Logging Configuration

Logging is configured via src/main/resources/logback-spring.xml.

  • Log File Location: Defaults to logs/app.log.
  • Rotation: Logs are rotated daily and archived in logs/archived/.
  • Console Output: Logs are also printed to the console (stdout).

To change the log level or file path, edit logback-spring.xml or override settings via command line arguments (e.g., --logging.file.name=/var/log/myapp.log).

3. Compilation

To build the application, navigate to the project root directory and run:

Linux/macOS:

./mvnw clean package -DskipTests

Windows:

mvnw.cmd clean package -DskipTests

This will generate an executable JAR file in the target/ directory (e.g., target/dbconnector-0.0.1-SNAPSHOT.jar).

4. Running the Application

To run the application using the built JAR file:

java -jar target/dbconnector-0.0.1-SNAPSHOT.jar

By default, the application runs on port 8080.

5. Network Configuration (FQDN & TLS)

By default, the application runs on localhost:8080. For production deployment, you likely want to use a Fully Qualified Domain Name (FQDN) and secure the connection with TLS (HTTPS).

5.1. Scenario A: HTTP with FQDN (No TLS)

If you are running behind a load balancer or proxy that handles SSL, or just want to use a domain name with HTTP:

  1. Server Configuration: No specific change is needed in the Java app if the port remains 8080.
  2. Webex Developer Portal:
    • Go to your Integration settings.
    • Add the new Redirect URI: http://your-fqdn.com:8080/login/oauth2/code/webex
    • (Note: Webex generally requires HTTPS for production integrations, but HTTP may work for testing).

5.2. Scenario B: HTTPS with FQDN (TLS Enabled)

To enable HTTPS directly on the Spring Boot application:

  1. Generate a Keystore: You need a PKCS12 keystore containing your SSL certificate.

    keytool -genkeypair -alias webex-connector -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 3650

    (Follow the prompts to set a password and certificate details)

  2. Update application.properties: Add the following SSL configurations:

    server.port=8443
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=YOUR_KEYSTORE_PASSWORD
server.ssl.key-store-type=PKCS12
server.ssl.key-alias=webex-connector

    Place the keystore.p12 file in src/main/resources/ or provide an absolute path (e.g., file:/etc/certs/keystore.p12).

  3. Webex Developer Portal:

    • Update the Redirect URI to use HTTPS and the new port: https://your-fqdn.com:8443/login/oauth2/code/webex

5.3. Important Note on Redirect URIs

Spring Security automatically calculates the {baseUrl} in the redirect URI based on the incoming request.

  • If you access the site via http://localhost:8080, the redirect URI sent to Webex is http://localhost:8080/login/oauth2/code/webex.
  • If you access via https://my-server.com, the redirect URI sent is https://my-server.com/login/oauth2/code/webex.

Crucial: The Redirect URI generated by the app MUST match exactly one of the Redirect URIs whitelisted in your Webex Integration settings.

6. Deployment as a Service (Linux Systemd)

To run the application as a background service on Linux:

  1. Create a service file: /etc/systemd/system/webex-connector.service

    [Unit]
Description=Webex DB Connector
After=syslog.target

[Service]
User=ubuntu
ExecStart=/usr/bin/java -jar /path/to/app/target/dbconnector-0.0.1-SNAPSHOT.jar
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

  2. Enable and start the service:

    sudo systemctl enable webex-connector
sudo systemctl start webex-connector