Documentation

Building Custom Docker Images

Create production-ready OpsOrch Core images with your adapter stack bundled as plugins.

Overview

OpsOrch Core ships as a minimal base image. To integrate with external systems like Jira, Prometheus, PagerDuty, or Elasticsearch, you add adapter plugins to the image. This guide shows you how to build custom images that bundle the exact plugins your stack needs.

When to use custom images:

•Bundle specific adapter plugins into a single, versioned image
•Deploy to environments where runtime plugin downloading isn't ideal
•Create immutable, reproducible images for production

Quick Start

Here's a minimal example adding Jira ticket support to OpsOrch Core:

Dockerfile

dockerfile

FROM ghcr.io / opsorch / opsorch - core:v0.2.0
WORKDIR / opt / opsorch

# Download Jira ticket plugin
ADD https://github.com/OpsOrch/opsorch-jira-adapter/releases/download/v0.1.0/ticketplugin-linux-amd64 ./plugins/ticketplugin
RUN chmod + x./ plugins / ticketplugin

# Configure plugin path
ENV OPSORCH_TICKET_PLUGIN = /opt/opsorch / plugins / ticketplugin

Build and Run

bash

docker build - t my - opsorch: latest.
docker run - p 8080: 8080 \
-e OPSORCH_TICKET_CONFIG = '{"apiToken":"...","email":"you@example.com","apiURL":"https://your-domain.atlassian.net","projectKey":"OPS"}' \
my - opsorch: latest

Multi-Adapter Production Example

A complete observability stack with incident management, metrics, logs, and messaging:

Dockerfile

dockerfile

FROM ghcr.io / opsorch / opsorch - core:v0.2.0
WORKDIR / opt / opsorch

# Incident Management(PagerDuty)
ADD https://github.com/OpsOrch/opsorch-pagerduty-adapter/releases/download/v0.1.5/incidentplugin-linux-amd64 ./plugins/incidentplugin
ADD https://github.com/OpsOrch/opsorch-pagerduty-adapter/releases/download/v0.1.5/serviceplugin-linux-amd64 ./plugins/serviceplugin

# Ticketing(Jira)
ADD https://github.com/OpsOrch/opsorch-jira-adapter/releases/download/v0.1.0/ticketplugin-linux-amd64 ./plugins/ticketplugin

# Metrics(Prometheus)
ADD https://github.com/OpsOrch/opsorch-prometheus-adapter/releases/download/v0.1.0/metricplugin-linux-amd64 ./plugins/metricplugin
ADD https://github.com/OpsOrch/opsorch-prometheus-adapter/releases/download/v0.1.0/alertplugin-linux-amd64 ./plugins/alertplugin

# Logs(Elasticsearch)
ADD https://github.com/OpsOrch/opsorch-elastic-adapter/releases/download/v0.1.0/logplugin-linux-amd64 ./plugins/logplugin

# Messaging(Slack)
ADD https://github.com/OpsOrch/opsorch-slack-adapter/releases/download/v0.1.0/messagingplugin-linux-amd64 ./plugins/messagingplugin

# Deployments & Teams(GitHub)
ADD https://github.com/OpsOrch/opsorch-github-adapter/releases/download/v0.1.0/deploymentplugin-linux-amd64 ./plugins/deploymentplugin
ADD https://github.com/OpsOrch/opsorch-github-adapter/releases/download/v0.1.0/teamplugin-linux-amd64 ./plugins/teamplugin

# Make all plugins executable
RUN chmod + x./ plugins/*

# Configure plugin paths
ENV OPSORCH_INCIDENT_PLUGIN=/opt/opsorch/plugins/incidentplugin \
    OPSORCH_SERVICE_PLUGIN=/opt/opsorch/plugins/serviceplugin \
    OPSORCH_TICKET_PLUGIN=/opt/opsorch/plugins/ticketplugin \
    OPSORCH_METRIC_PLUGIN=/opt/opsorch/plugins/metricplugin \
    OPSORCH_ALERT_PLUGIN=/opt/opsorch/plugins/alertplugin \
    OPSORCH_LOG_PLUGIN=/opt/opsorch/plugins/logplugin \
    OPSORCH_MESSAGING_PLUGIN=/opt/opsorch/plugins/messagingplugin \
    OPSORCH_DEPLOYMENT_PLUGIN=/opt/opsorch/plugins/deploymentplugin \
    OPSORCH_TEAM_PLUGIN=/opt/opsorch/plugins/teamplugin

.env Configuration

bash

# Core Configuration
OPSORCH_BEARER_TOKEN=your-secure-random-token-here

# PagerDuty Incident Configuration
OPSORCH_INCIDENT_CONFIG={"apiToken":"pdtoken_xxxxx","serviceID":"P123456","fromEmail":"oncall@example.com","apiURL":"https://api.pagerduty.com"}

# Jira Ticket Configuration
OPSORCH_TICKET_CONFIG={"apiToken":"jira_token_xxxxx","email":"bot@example.com","apiURL":"https://your-domain.atlassian.net","projectKey":"OPS"}

# Prometheus Metrics Configuration
OPSORCH_METRIC_CONFIG={"url":"http://prometheus:9090"}

# Elasticsearch Logs Configuration
OPSORCH_LOG_CONFIG={"addresses":["http://elasticsearch:9200"],"username":"elastic","password":"changeme","indexPattern":"logs-*"}

# Slack Messaging Configuration
OPSORCH_MESSAGING_CONFIG={"token":"xoxb-your-slack-bot-token"}

# GitHub Deployment & Team Configuration
OPSORCH_DEPLOYMENT_CONFIG={"token":"ghp_xxxxx","owner":"your-org","repo":"your-repo"}
OPSORCH_TEAM_CONFIG={"token":"ghp_xxxxx","organization":"your-org"}

Adapter Configuration Reference

Each adapter requires specific configuration passed via OPSORCH_{CAPABILITY}_CONFIG environment variables.

PagerDuty (Incident & Service)

json

{
  "apiToken": "your-pagerduty-api-token",
  "serviceID": "PXXXXXX",
  "fromEmail": "oncall@example.com",
  "apiURL": "https://api.pagerduty.com"
}

Get API token from PagerDuty: Integrations → API Access Keys. Find Service ID in your service URL.

Jira (Ticket)

json

{
  "apiToken": "your-jira-api-token",
  "email": "bot@example.com",
  "apiURL": "https://your-domain.atlassian.net",
  "projectKey": "OPS"
}

Create API token at: Atlassian API tokens

Prometheus (Metric & Alert)

json

{
  "url": "http://prometheus:9090"
}

// For alerts (Alertmanager):
{
  "alertmanagerURL": "http://alertmanager:9093"
}

Elasticsearch (Log)

json

{
  "addresses": ["http://elasticsearch:9200"],
  "username": "elastic",
  "password": "your-password",
  "indexPattern": "logs-*"
}

Slack (Messaging)

json

{
  "token": "xoxb-your-slack-bot-token"
}

Required scopes: chat:write, channels:read,groups:read

GitHub (Ticket, Deployment, Team)

json

{
  "token": "ghp_your-github-token",
  "owner": "your-org",
  "repo": "your-repo",
  "organization": "your-org"
}

Required scopes: repo, read:org,read:user

Troubleshooting

Plugin Not Loading

Symptom: API returns 501 Not Implemented with error {capability}_provider_missing

bash

# Check file permissions
docker exec -it <container> ls -la /opt/opsorch/plugins/

# Verify plugin path
docker exec -it <container> env | grep OPSORCH_

# Test plugin directly
docker exec -it <container> /opt/opsorch/plugins/ticketplugin

# Check logs
docker logs <container>

Configuration Validation Errors

Symptom: Plugin loads but API calls fail with authentication errors

bash

# Validate JSON syntax
echo $OPSORCH_TICKET_CONFIG | jq .

# Check required fields
echo $OPSORCH_TICKET_CONFIG | jq 'has("apiToken") and has("email")'

# Test credentials manually (Jira example)
curl -u 'email:apiToken' \
  "https://your-domain.atlassian.net/rest/api/3/myself"

Common Error Messages

Error	Meaning	Solution
provider_missing	No plugin configured	Set OPSORCH_{CAP}_PLUGIN env var
plugin_not_found	Binary doesn't exist	Check file path and permissions
auth_failed	Invalid credentials	Verify API tokens in config
invalid_config	Missing required fields	Check adapter README

Production Best Practices

Security

✓Never commit secrets to Docker images - inject at runtime
✓Use Kubernetes Secrets or vault for credential management
✓Run containers as non-root user when possible
✓Scan images for vulnerabilities with docker scan or trivy

Versioning

✓Pin versions for core image and adapter plugins
✓Use semantic versioning for your custom images
✓Tag images with git commit SHA for traceability

Health Checks

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

Resource Limits

yaml

resources:
  limits:
    memory: 512M
    cpus: '0.5'
  reservations:
    memory: 256M
    cpus: '0.25'

Next Steps

→Review the complete guide on GitHub for more examples
→Check adapter repositories for detailed configuration options
→Deploy to Kubernetes with Helm charts
→Join GitHub Discussions for community support