Skip to content
SENSE LogoSENSE Operations Manual
Release Notes

SENSE-O on Docker (WIP)

This document is a deployment template for the SENSE Orchestrator and remains WIP. It describes how to deploy (IPv4 and IPv6) StackV using Docker and how to verify connectivity. It also includes notes for troubleshooting Docker’s IPv6 limitations.

Installing Docker

Section titled “Installing Docker”

  • sudo yum install -y docker (or use your distro’s package manager)

  • sudo systemctl enable docker && sudo systemctl start docker

IPv4 Deployment

Section titled “IPv4 Deployment”

TODO

Credential Store Configuration

Section titled “Credential Store Configuration”

Configure the credential store before enabling a workflow that uses stored tokens.

  1. Choose a current key source and prepare its versioned value as described in Configure the Credential Store. Retain existing keys if the database already contains credentials; use the rotation procedure when changing keys.

  2. For inline configuration, set SENSE_CRED_KEY in docker/.env. The base docker-compose.local.yml and docker-compose.remote.yml pass this value and SENSE_CRED_KEY_PREVIOUS to the application. Keep .env protected and out of version control.

  3. For file configuration, add a Compose override, for example docker/docker-compose.credential-files.yml:

    services:
      app:
        environment:
          SENSE_CRED_KEY: ""
          SENSE_CRED_KEY_FILE: /run/secrets/sense_cred_key
        volumes:
          - /path/to/current-credential-key:/run/secrets/sense_cred_key:ro

    Replace the host path with an existing protected key file readable by the application’s container user. The empty inline value prevents a conflict with SENSE_CRED_KEY from the base file. The base Compose files do not forward _FILE variables or mount files: adding a path to .env alone is insufficient.

    If previous keys are needed, also clear SENSE_CRED_KEY_PREVIOUS, set SENSE_CRED_KEY_PREVIOUS_FILE to its container path, and add a read-only mount for that file. Previous-key file contents use the format in the configuration guide.

  4. From the StackV docker directory, recreate the application after inline configuration changes:

    Terminal window
    docker compose -f docker-compose.local.yml up -d --force-recreate app

    For file configuration, include the override on every recreation:

    Terminal window
    docker compose -f docker-compose.local.yml -f docker-compose.credential-files.yml up -d --force-recreate app

    Substitute docker-compose.remote.yml when using that deployment template, and retain any other Compose files used by the deployment. docker compose restart alone does not refresh the container’s environment.

  5. As a SENSE System Admin, open Admin Settings → Credentials. Confirm Store Active, the expected Key Version, any needed previous keys marked LOADED, and no key or verification warnings. See credential-store diagnostics if these checks fail.

IPv6 Deployment

Section titled “IPv6 Deployment”

Docker Host Configuration for IPv6

Section titled “Docker Host Configuration for IPv6”

For Docker containers to communicate over IPv6, the Docker daemon must be configured to manage an IPv6 subnet.

  1. Edit the Docker Daemon Configuration File:

    Open or create the file /etc/docker/daemon.json. Add the following configuration to enable IPv6 and assign a default address pool for Docker networks.

    {
      "ipv6": true,
      "fixed-cidr-v6": "2001:db8:21::/64"
    }

    Note: 2001:db8::/32 is a prefix reserved for documentation. For production, it is recommended to use a Unique Local Address (ULA) prefix from your organization’s assigned block.

  2. Apply the Configuration

    Restart the Docker service for the changes to take effect.

    sudo systemctl restart docker

Verifying Bidirectional IPv6 Connectivity

Section titled “Verifying Bidirectional IPv6 Connectivity”

Verification is a two-part process to confirm traffic can flow in both directions.

Part A: Outbound Verification (Client \u2192 StackV Server)

This tests if you can reach the containerized service from an external machine (e.g., your laptop).

  1. Check Local Machine’s IPv6 Connectivity:

    Get your public IPv6 address

    • curl -6 -s https://v6.ident.me

  2. Resolve the Server’s IPv6 Address:

    Confirm the AAAA DNS record points to the host’s IPv6

    • dig AAAA <YOUR_HOSTNAME_OR_DOMAIN> +short

  3. Test Network and Port Reachability:

    Ping the host machine

    • ping -6 <HOST_IPV6>

    Check if the application port (8443) is open

    • nc -6vz <HOST_IPV6> <APP_PORT>

  4. Test the Application Service:

    Connect to the application using its hostname

    • curl -6 -v -k https://<YOUR_HOSTNAME_OR_DOMAIN>:<APP_PORT>/StackV-web/portal/

    Or, connect directly using the host’s IPv6 address (note the brackets)

    • curl -6 -v -k "https://[<HOST_IPV6>]:<APP_PORT>/yourapp/portal/"

Part B: Inbound Verification (StackV Server \u2192 Client)

This crucial test confirms the return path is clear by having the remote server connect back to a service running on your local machine.

  1. Prepare Your Local Machine:

    • Find your current global IPv6 address: curl -6 https://v6.ident.me/
    • Ensure your local firewall is not blocking incoming traffic on test ports (e.g., 44444, 8080).

  2. Set Up Test Listeners on Your Local Machine:

    • Option 1: Simple TCP Listener with ncat

      On your local machine, listen on port 44444 for any IPv6 connection

      • sudo ncat -6 -l -p 44444 --keep-open

      Verify with:

      • ss -lntp | grep 44444

    • Option 2: HTTP Server with Docker (nginx)

      Run a temporary nginx container publishing port 8080 on IPv6

      • docker run -d --name test-nginx -p "[::]:8080:80" nginx:alpine

      Verify it is listening on [::]:8080

      • ss -lntp | grep 8080

  3. Execute the Test from the Remote Server:

    • SSH into the remote server where StackV is running.
    • Use your local machine’s IPv6 address (LOCAL_IPV6) found in step 1.

    Test the ncat listener

    • nc -6vz [<LOCAL_IPV6>] 44444

    Test the nginx HTTP server

    • curl -6 -v http://[<LOCAL_IPV6>]:8080

    Expected results: nc should report “Connection succeeded”, and curl should return the “Welcome to nginx!” HTML page. If these tests time out, proceed to troubleshooting.

Troubleshooting Common Issues

Section titled “Troubleshooting Common Issues”

  • Issue: Inbound Tests Fail (Timeout)

    • Cause: This is often due to asymmetric routing, especially if your local machine is on a VPN. The server’s connection request (SYN) arrives via your Wi-Fi/Ethernet, but your machine’s reply (SYN-ACK) is incorrectly routed out through the VPN, breaking the handshake.

    • Diagnosis: On your local machine, use tcpdump to watch for incoming packets: sudo tcpdump -i any -n ‘host REMOTE_HOST_IPV6 and port TEST_PORT’. If you see a SYN packet arrive but no reply is sent from your physical interface, asymmetric routing is the likely cause.

    • Solution: Add a specific route on your local machine to force replies to the server to bypass the VPN. Find your default gateway (ip -6 route | grep default) and add the route:

      • sudo ip -6 route add <REMOTE_HOST_IPV6> via <your_gateway_link_local_address> dev <your_physical_interface

  • Issue: Service is Not Listening on IPv6

    • Cause: Docker did not bind the port to the host’s IPv6 address.

    • Diagnosis: On the remote host, run ss -lntp | grep APP_PORT. The output must show a listener on [::]:APP_PORT or :::APP_PORT. If it only shows 0.0.0.0:APP_PORT, it is only listening on IPv4.

    • Solution: Ensure your docker-compose.yml uses the [::]:<HOST_PORT>:<CONTAINER_PORT> syntax in the ports section. This explicitly tells Docker to create an IPv6 binding.