feat: add Apprise notification integration for deployment status updates

Author: kimdre

cmd/doco-cd/http_handler.go

@@ -11,6 +11,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/kimdre/doco-cd/internal/notification"
+
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/docker/api/types/container"
@@ -44,6 +46,8 @@ func onError(repoName string, w http.ResponseWriter, log *slog.Logger, errMsg st
 		details,
 		jobID,
 		statusCode)
+
+	_ = notification.Send(notification.Failure, "Deployment ßFailed", errMsg)
 }
 
 // getRepoName extracts the repository name from the clone URL.

cmd/doco-cd/poll_handler.go

@@ -10,6 +10,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/kimdre/doco-cd/internal/notification"
+
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/pkg/api"
 	"github.com/docker/docker/api/types/container"
@@ -87,6 +89,11 @@ func (h *handlerData) PollHandler(pollJob *config.PollJob) {
 				err := RunPoll(context.Background(), pollJob.Config, h.appConfig, h.dataMountPoint, h.dockerCli, h.dockerClient, logger)
 				if err != nil {
 					prometheus.PollErrors.WithLabelValues(repoName).Inc()
+
+					err = notification.Send(notification.Failure, "Deployment Failed", err.Error())
+					if err != nil {
+						logger.Error("failed to send notification", log.ErrAttr(err))
+					}
 				}
 
 				lock.Unlock()

dev.compose.yaml

@@ -17,6 +17,7 @@ services:
     restart: unless-stopped
     depends_on:
       - proxy
+      - apprise
     ports:
       - "80:80"
       - "9120:9120"
@@ -30,6 +31,9 @@ services:
       <<: *poll-config
       #POLL_CONFIG_FILE: /poll.yml
       HTTP_PROXY: http://username:password@proxy:8888
+      APPRISE_API_URL: http://apprise:8000/notify
+      APPRISE_NOTIFY_LEVEL: info
+      # APPRISE_NOTIFY_URLS: # .env
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - data:/data
@@ -51,6 +55,15 @@ services:
       - source: tinyproxy.conf
         target: /etc/tinyproxy/tinyproxy.conf
 
+  apprise:
+    image: caronc/apprise:latest
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      TZ: Europe/Berlin
+      APPRISE_WORKER_COUNT: 1
+
 volumes:
   data:
 

internal/config/app_config.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/kimdre/doco-cd/internal/notification"
+
 	"github.com/caarlos0/env/v11"
 	"github.com/go-git/go-git/v5/plumbing/transport"
 	"gopkg.in/validator.v2"
@@ -15,23 +17,27 @@ const AppName = "doco-cd" // Name of the application
 // AppConfig is used to configure this application
 // https://github.com/caarlos0/env?tab=readme-ov-file#env-tag-options
 type AppConfig struct {
-	LogLevel            string                 `env:"LOG_LEVEL,notEmpty" envDefault:"info"`                          // LogLevel is the log level for the application
-	HttpPort            uint16                 `env:"HTTP_PORT,notEmpty" envDefault:"80" validate:"min=1,max=65535"` // HttpPort is the port the HTTP server will listen on
-	HttpProxyString     string                 `env:"HTTP_PROXY"`                                                    // HttpProxyString is the HTTP proxy URL as a string
-	HttpProxy           transport.ProxyOptions // HttpProxy is the HTTP proxy configuration parsed from the HttpProxyString
-	WebhookSecret       string                 `env:"WEBHOOK_SECRET"`                                                     // WebhookSecret is the secret used to authenticate the webhook
-	WebhookSecretFile   string                 `env:"WEBHOOK_SECRET_FILE,file"`                                           // WebhookSecretFile is the file containing the WebhookSecret
-	GitAccessToken      string                 `env:"GIT_ACCESS_TOKEN"`                                                   // GitAccessToken is the access token used to authenticate with the Git server (e.g. GitHub) for private repositories
-	GitAccessTokenFile  string                 `env:"GIT_ACCESS_TOKEN_FILE,file"`                                         // GitAccessTokenFile is the file containing the GitAccessToken
-	AuthType            string                 `env:"AUTH_TYPE,notEmpty" envDefault:"oauth2"`                             // AuthType is the type of authentication to use when cloning repositories
-	SkipTLSVerification bool                   `env:"SKIP_TLS_VERIFICATION,notEmpty" envDefault:"false"`                  // SkipTLSVerification skips the TLS verification when cloning repositories.
-	DockerQuietDeploy   bool                   `env:"DOCKER_QUIET_DEPLOY,notEmpty" envDefault:"true"`                     // DockerQuietDeploy suppresses the status output of dockerCli in deployments (e.g. pull, create, start)
-	DockerSwarmFeatures bool                   `env:"DOCKER_SWARM_FEATURES,notEmpty" envDefault:"true"`                   // DockerSwarmFeatures enables the usage Docker Swarm features in the application if it has detected that it is running in a Docker Swarm environment
-	PollConfigYAML      string                 `env:"POLL_CONFIG"`                                                        // PollConfigYAML is the unparsed string containing the PollConfig in YAML format
-	PollConfigFile      string                 `env:"POLL_CONFIG_FILE,file"`                                              // PollConfigFile is the file containing the PollConfig in YAML format
-	PollConfig          []PollConfig           `yaml:"-"`                                                                 // PollConfig is the YAML configuration for polling Git repositories for changes
-	MaxPayloadSize      int64                  `env:"MAX_PAYLOAD_SIZE,notEmpty" envDefault:"1048576"`                     // MaxPayloadSize is the maximum size of the payload in bytes that the HTTP server will accept (default 1MB = 1048576 bytes)
-	MetricsPort         uint16                 `env:"METRICS_PORT,notEmpty" envDefault:"9120" validate:"min=1,max=65535"` // MetricsPort is the port the prometheus metrics server will listen on
+	LogLevel              string                 `env:"LOG_LEVEL,notEmpty" envDefault:"info"`                          // LogLevel is the log level for the application
+	HttpPort              uint16                 `env:"HTTP_PORT,notEmpty" envDefault:"80" validate:"min=1,max=65535"` // HttpPort is the port the HTTP server will listen on
+	HttpProxyString       string                 `env:"HTTP_PROXY"`                                                    // HttpProxyString is the HTTP proxy URL as a string
+	HttpProxy             transport.ProxyOptions // HttpProxy is the HTTP proxy configuration parsed from the HttpProxyString
+	WebhookSecret         string                 `env:"WEBHOOK_SECRET"`                                                     // WebhookSecret is the secret used to authenticate the webhook
+	WebhookSecretFile     string                 `env:"WEBHOOK_SECRET_FILE,file"`                                           // WebhookSecretFile is the file containing the WebhookSecret
+	GitAccessToken        string                 `env:"GIT_ACCESS_TOKEN"`                                                   // GitAccessToken is the access token used to authenticate with the Git server (e.g. GitHub) for private repositories
+	GitAccessTokenFile    string                 `env:"GIT_ACCESS_TOKEN_FILE,file"`                                         // GitAccessTokenFile is the file containing the GitAccessToken
+	AuthType              string                 `env:"AUTH_TYPE,notEmpty" envDefault:"oauth2"`                             // AuthType is the type of authentication to use when cloning repositories
+	SkipTLSVerification   bool                   `env:"SKIP_TLS_VERIFICATION,notEmpty" envDefault:"false"`                  // SkipTLSVerification skips the TLS verification when cloning repositories.
+	DockerQuietDeploy     bool                   `env:"DOCKER_QUIET_DEPLOY,notEmpty" envDefault:"true"`                     // DockerQuietDeploy suppresses the status output of dockerCli in deployments (e.g. pull, create, start)
+	DockerSwarmFeatures   bool                   `env:"DOCKER_SWARM_FEATURES,notEmpty" envDefault:"true"`                   // DockerSwarmFeatures enables the usage Docker Swarm features in the application if it has detected that it is running in a Docker Swarm environment
+	PollConfigYAML        string                 `env:"POLL_CONFIG"`                                                        // PollConfigYAML is the unparsed string containing the PollConfig in YAML format
+	PollConfigFile        string                 `env:"POLL_CONFIG_FILE,file"`                                              // PollConfigFile is the file containing the PollConfig in YAML format
+	PollConfig            []PollConfig           `yaml:"-"`                                                                 // PollConfig is the YAML configuration for polling Git repositories for changes
+	MaxPayloadSize        int64                  `env:"MAX_PAYLOAD_SIZE,notEmpty" envDefault:"1048576"`                     // MaxPayloadSize is the maximum size of the payload in bytes that the HTTP server will accept (default 1MB = 1048576 bytes)
+	MetricsPort           uint16                 `env:"METRICS_PORT,notEmpty" envDefault:"9120" validate:"min=1,max=65535"` // MetricsPort is the port the prometheus metrics server will listen on
+	AppriseApiURL         HttpUrl                `env:"APPRISE_API_URL" validate:"httpUrl"`                                 // AppriseApiURL is the URL of the Apprise notification service
+	AppriseNotifyUrls     string                 `env:"APPRISE_NOTIFY_URLS"`                                                // AppriseNotifyUrls is a comma-separated list of URLs to notify via the Apprise notification service
+	AppriseNotifyUrlsFile string                 `env:"APPRISE_NOTIFY_URLS_FILE,file"`                                      // AppriseNotifyUrlsFile is the file containing the AppriseNotifyUrls
+	AppriseNotifyLevel    string                 `env:"APPRISE_NOTIFY_LEVEL,notEmpty" envDefault:"info"`                    // AppriseNotifyLevel is the level of notifications to send via the Apprise notification service
 }
 
 // GetAppConfig returns the configuration.
@@ -83,18 +89,26 @@ func GetAppConfig() (*AppConfig, error) {
 		}
 	}
 
+	notification.SetAppriseConfig(
+		string(cfg.AppriseApiURL),
+		cfg.AppriseNotifyUrls,
+		cfg.AppriseNotifyLevel,
+	)
+
 	return &cfg, nil
 }
 
 // loadFileBasedEnvVars loads environment variables from files if the corresponding file-based environment variable is set.
 func loadFileBasedEnvVars(cfg *AppConfig) error {
 	fields := []struct {
-		fileField string
-		value     *string
-		name      string
+		fileField  string
+		value      *string
+		name       string
+		allowUnset bool
 	}{
-		{cfg.WebhookSecretFile, &cfg.WebhookSecret, "WEBHOOK_SECRET"},
-		{cfg.GitAccessTokenFile, &cfg.GitAccessToken, "GIT_ACCESS_TOKEN"},
+		{cfg.WebhookSecretFile, &cfg.WebhookSecret, "WEBHOOK_SECRET", false},
+		{cfg.GitAccessTokenFile, &cfg.GitAccessToken, "GIT_ACCESS_TOKEN", false},
+		{cfg.AppriseNotifyUrlsFile, &cfg.AppriseNotifyUrls, "APPRISE_NOTIFY_URLS", true},
 	}
 
 	for _, field := range fields {
@@ -104,7 +118,7 @@ func loadFileBasedEnvVars(cfg *AppConfig) error {
 			}
 
 			*field.value = field.fileField
-		} else if *field.value == "" {
+		} else if *field.value == "" && !field.allowUnset {
 			return fmt.Errorf("%w: %s or %s", ErrBothSecretsNotSet, field.name, field.name+"_FILE")
 		}
 	}

internal/docker/compose.go

@@ -19,6 +19,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/kimdre/doco-cd/internal/notification"
+
 	"github.com/go-git/go-git/v5/plumbing/format/diff"
 
 	"github.com/docker/docker/client"
@@ -568,6 +570,11 @@ func DeployStack(
 	prometheus.DeploymentsTotal.WithLabelValues(deployConfig.Name).Inc()
 	prometheus.DeploymentDuration.WithLabelValues(deployConfig.Name).Observe(time.Since(startTime).Seconds())
 
+	err = notification.Send(notification.Success, "Deployment Successful", "Successfully deployed stack "+deployConfig.Name)
+	if err != nil {
+		return err
+	}
+
 	return nil
 }
 

internal/notification/notification.go

@@ -0,0 +1,117 @@
+package notification
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+)
+
+type level int
+
+const (
+	Info    level = iota // Informational messages
+	Success              // Successful operations
+	Warning              // Warning messages indicating potential issues
+	Failure              // Error messages indicating failure of operations
+)
+
+var logLevels = map[level]string{
+	Info:    "info",
+	Success: "success",
+	Warning: "warning",
+	Failure: "failure",
+}
+
+var levelEmojis = map[level]string{
+	Info:    "ℹ️",
+	Success: "✅",
+	Warning: "⚠️",
+	Failure: "❌",
+}
+
+var (
+	appriseApiURL      = ""
+	appriseNotifyUrls  = ""
+	appriseNotifyLevel = Info
+)
+
+// appriseRequest represents the structure of a request to the Apprise notification service.
+type appriseRequest struct {
+	NotifyUrls string `json:"urls"`
+	Title      string `json:"title"`
+	Body       string `json:"body"`
+	Type       string `json:"type,omitempty"` // Optional field for specifying the type of notification (info, success, error, failure)
+}
+
+// parseLevel converts a string representation of a log level to the level type.
+func parseLevel(level string) level {
+	switch level {
+	case logLevels[Info]:
+		return Info
+	case logLevels[Success]:
+		return Success
+	case logLevels[Warning]:
+		return Warning
+	case logLevels[Failure]:
+		return Failure
+	default:
+		return Info // Default to Info if the level is not recognized
+	}
+}
+
+// send a notification to the Apprise service.
+func send(apiUrl, notifyUrls, title, message, level string) error {
+	jsonData, err := json.Marshal(appriseRequest{
+		NotifyUrls: notifyUrls,
+		Title:      title,
+		Body:       message,
+		Type:       level,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to marshal appriseRequest: %w", err)
+	}
+
+	resp, err := http.Post(apiUrl, "application/json", bytes.NewBuffer(jsonData)) // #nosec G107
+	if err != nil {
+		return fmt.Errorf("failed to send request to Apprise: %w", err)
+	}
+
+	defer resp.Body.Close() // nolint:errcheck
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("apprise request failed with status: %s", resp.Status)
+	}
+
+	return nil
+}
+
+// SetAppriseConfig sets the configuration for the Apprise notification service.
+func SetAppriseConfig(apiURL, notifyUrls, notifyLevel string) {
+	appriseApiURL = apiURL
+	appriseNotifyUrls = notifyUrls
+	appriseNotifyLevel = parseLevel(notifyLevel)
+}
+
+// Send sends a notification using the Apprise service based on the provided configuration and parameters.
+func Send(level level, title, message string) error {
+	if appriseApiURL == "" || appriseNotifyUrls == "" {
+		return nil
+	}
+
+	if level < appriseNotifyLevel {
+		return nil // Do not send notification if the level is lower than the configured level
+	}
+
+	title = levelEmojis[level] + " " + title
+
+	message = strings.Replace(message, ": ", ":\n", 1)
+
+	err := send(appriseApiURL, appriseNotifyUrls, title, message, logLevels[level])
+	if err != nil {
+		return fmt.Errorf("failed to send notification: %w", err)
+	}
+
+	return nil
+}