---
title: homepage-agent Stack
description: Migration to swarm configuration
published: true
date: 2026-05-06T14:37:49.849Z
tags: docker,swarm,homepage-agent,netgrimoire
editor: markdown
dateCreated: 2026-05-06T14:37:49.849Z
---

# homepage-agent

## Overview
The homepage-agent stack is a Docker Swarm configuration for the homepage service in NetGrimoire. It consists of four services: `homepage-agent-docker3`, `homepage-agent-docker4`, `homepage-agent-docker5`, and `homepage-agent-znas`. These services are replicas of the same image, with slightly different port numbers and labels.

## Architecture

| Service | Image | Port | Role |
|---------|-------|------|------|
- **Host:** docker4
- **Network:** netgrimoire
- **Exposed via:** caddy.docker3:4111, internal
- **Homepage group:** homepage.group

## Build & Configuration

### Prerequisites
To build this stack, you need to have Docker Swarm installed and running.

### Volume Setup
```bash
mkdir -p /DockerVol/homepage-agent-docker3
chown -R docker:docker /DockerVol/homepage-agent-docker3
```

```bash
mkdir -p /DockerVol/homepage-agent-docker4
chown -R docker:docker /DockerVol/homepage-agent-docker4
```

```bash
mkdir -p /DockerVol/homepage-agent-docker5
chown -R docker:docker /DockerVol/homepage-agent-docker5
```

```bash
mkdir -p /DockerVol/homepage-agent-znas
chown -R docker:docker /DockerVol/homepage-agent-znas
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
PUID=1964
PGID=1964
HOMEPAGE_AGENT_PORT=4111
CADDY_SKIP=true
HOME_PAGE_SKIP=true
MONITOR_SKIP=true
DIUN_ENABLE=true

# generate: openssl rand -hex 32
PUID=1964
PGID=1964
HOMEPAGE_AGENT_PORT=4112
CADDY_SKIP=true
HOME_PAGE_SKIP=true
MONITORSKIP=true
DIUN_ENABLE=true

# generate: openssl rand -hex 32
PUID=1964
PGID=1964
HOMEPAGE_AGENT_PORT=4113
CADDY_SKIP=true
HOME_PAGE_SKIP=true
MONITOR_SKIP=true
DIUN_ENABLE=true

# generate: openssl rand -hex 32
PUID=1964
PGID=1964
HOMEPAGE_AGENT_PORT=4114
CADDY_SKIP=true
HOME_PAGE_SKIP=true
MONITORSKIP=true
DIUN_ENABLE=true
```

### Deploy
```bash
cd services/swarm/stack/homepage-agent
set -a && source .env && set +a
docker stack config --compose-file homepage-agent-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml homepage-agent
rm resolved.yml
docker stack services homepage-agent
```

### First Run
Perform the following steps after deploying the stack for the first time:

```bash
# Initialize Kuma for monitoring
kuma init

# Start Uptime Kuma for monitoring
kuma start -d

# Check service logs for errors
docker service logs --follow homepage-agent-docker3
```

## User Guide

### Accessing homepage-agent
| Service | URL | Purpose |
|---------|-----|---------|
- **Home Page:** caddy.docker3:4111
- **Admin Panel:** None

### Primary Use Cases
To use the homepage-agent service, you can access it through the admin panel. Please note that the admin panel is not currently available.

### NetGrimoire Integrations
The homepage-agent service connects to other services in NetGrimoire through environment variables and labels. Specifically, it connects to `diun` for integration with the DiUn server.

## Operations

### Monitoring
Use Kuma to monitor the status of the homepage-agent service.

```bash
docker stack services homepage-agent
kuma status
```

### Backups
Critical data is stored in `/DockerVol/homepage-agent-docker3` and `/DockerVol/homepage-agent-docker4`. Ensure that these directories are backed up regularly.

### Restore
To restore the service, run the following command:

```bash
./deploy.sh
```

## Common Failures
| Failure Mode | Symptoms | Cause | Fix |
|-------------|----------|-------|------|
- **Port in Use**: Port is already in use by another process.
    - Symptoms: Service cannot be started.
    - Cause: Another service is using the same port.
    - Fix: Stop the other service and try again.
- **Kuma Connection Error**: Kuma connection fails.
    - Symptoms: Service logs contain error messages about Kuma connection failures.
    - Cause: Kuma is not running or there is an issue with the configuration.
    - Fix: Check the Kuma logs and adjust the configuration as needed.

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-06 | 9e8a2087 | Initial documentation creation. |
| 2026-05-06 | 3b8f1795 | Added initial services and configuration. |

# Notes
- Generated by Gremlin on 2026-05-06T14:37:49.849Z
- Source: swarm/homepage-agent.yaml
- Review User Guide and Changelog sections