Docker Instance Management Guide

Docker instances let you deploy the GIIP agent as a container on a remote PC/server and manage it from the GIIP web interface. Once you provide the instance token to the target machine and start the container, that machine begins acting as a GIIP agent (polling every minute) and optionally as a slack-bot.

🏢 Go to Docker Instance Management →

📋 Overview

The Docker Instance Management page lets you create and manage Docker container instances for deploying the giip-fde-agent to remote machines. When you create an instance, GIIP server encrypts credentials with AES-256-GCM and issues a single-use bootstrap token.

⚠️ This page requires admin access. You must have uLevel >= 70 to access it. Users below this level are redirected to the home page.

🔍 Page Layout

1. Header

• Page title: "Docker Instance Management"
• + Create Docker instance button: Opens the creation modal.

2. Instance List Table

Column	Description
Label	Instance name (falls back to #<diSn> if not set)
Created	Creation timestamp
Last fetched	Last time the container used the token to fetch env from GIIP. This is NOT real-time liveness — it's the last activation time.
Status	Active (green) or Revoked (red) badge
Actions	Revoke button — invalidates the token (does not stop a running container)

⚠️ When Last fetched is -: The container has never been started. You have not yet run Procedure ① (manual) or ② (Provision now).

🛠️ Creating an Instance

1. Click + Create Docker instance.
2. Fill in the 3 required fields:
   • GIIP_LOGIN_ID: Your GIIP login account (e.g., user@example.com)
   • GIIP_SK: Your GIIP secret key (different from password)
   • GIIP_CSN: Your CSN number (e.g., 47)
3. Optional fields:
   • Label: Instance name (e.g., lowy-dp01-docker)
   • GIIP_PROJECT_NAME: Defaults to docker
   • GIIP_WORKDIR: Working directory (optional)
   • GIIP_REST_BRANCH: Git branch (optional)
   • SLACK_BOT_TOKEN / SLACK_APP_TOKEN / SLACK_CHANNEL_ID: Slack bot (optional — requires both tokens)
   • Enable hourly-issue-scheduler: Checkbox (on by default) — runs the issue scheduler at :07 every hour
4. Click Create.

Copy the token immediately

After creation, the token is shown exactly once.

GIIP_INSTANCE_TOKEN=<token>

Closing the modal permanently hides the token. You need this token to start the container, so copy it before proceeding.

🛠️ Starting the Container After Creation — Method ① (Manual, all environments)

After copying the token, run the following on the target PC/server:

# 1. Clone the giip-fde-agent repo
git clone https://github.com/LowyShin/giip-fde-agent.git
cd giip-fde-agent/docker

# 2. Write only the token to .env
echo 'GIIP_INSTANCE_TOKEN=<copied token>' > .env

# 3. Start with Docker Compose
docker compose up -d --build

• Only the token is needed in .env. The fetch-instance-env.sh script fetches the remaining env vars from the dockerInstanceFetch API (using the token itself as credentials).
• If you add other keys directly in .env, those values take priority (partial override supported).

🛠️ Starting the Container After Creation — Method ② (Remote "Provision now")

Only available if the target PC already has a GIIP agent running with an existing lssn.

1. Enter the target PC's lssn in the lssn input field on the token display screen.
2. Click [Provision now].
3. A bootstrap script (mssn=6122) is queued and immediately force-executed (CQERunForce).

⚠️ This only works if GIIP agent is already installed on the target PC. If the agent is not present, use Method ① instead.

⚠️ Script ownership constraint: The bootstrap script runs under a specific owner account. If you press this button from a different account, it fails — but the instance is already created and the token is still valid. Proceed with Method ① (manual) in this case.

⚠️ Takes up to 1 minute: The GIIP agent on the target PC polls approximately every 60 seconds, so wait up to 1 minute for the container to start.

🔍 Verifying "Connection" After Creation — 3 Paths

There is no terminal inside GIIP web to connect to the container. Verification is done through these 3 methods.

1. Shell Access (on target PC)

docker exec -it giip-fde-agent bash

The container name is always giip-fde-agent.

2. Log Review (on target PC)

docker compose logs -f          # from the docker/ directory
docker logs -f giip-fde-agent   # from anywhere

If startup succeeded, you will see:

• [entrypoint] cloned ...
• [fetch-instance-env] env applied from GIIP_INSTANCE_TOKEN
• [entrypoint] registered giipAgentLinux cron (every 1 min)
• [entrypoint] ready. tailing logs.

3. GIIP Web Verification — lsvrlist (Server List)

This is the canonical "how to verify from GIIP web" method.

On container startup:

1. giipAgentLinux is cloned.
2. giipAgent.cnf (sk=registered GIIP_SK, lssn="0") is created.
3. giipAgent3.sh runs every minute.
4. GIIP automatically assigns an lssn, which is then persisted in the cnf file for subsequent restarts.
5. The container now appears in lsvrlist alongside other servers.

Verification path: /en/lsvrlist → find the relevant lssn → lsvrdetail → check tLSvr.lsChkdt heartbeat for liveness

⚠️ Without GIIP_SK or with GIIP_ENABLE_AGENT=false, this registration does not happen and you cannot see the container status in GIIP web.

4. Slack Verification (with Slack bot)

If you provided both SLACK_BOT_TOKEN and SLACK_APP_TOKEN, the slack-bot starts via pm2. If the bot responds in the configured channel, it is running correctly.

⚠️ If either token is missing, the bot is skipped entirely. Having only one token and seeing nothing is expected behavior.

💡 Notes

• Last fetched ≠ real-time liveness: Last fetched shows "when the container last pulled env from GIIP." If the container is stopped, this value remains unchanged. For real-time status, check the lsvrlist heartbeat.
• Revoke does not delete the row: Revoke only invalidates the token; the row remains as an audit trail with a Revoked badge.
• Revoke does not stop a running container. You must run docker compose down on the target PC to stop it.
• Container name is always giip-fde-agent: Fixed in docker-compose.yml.

Troubleshooting

Symptom	Cause	Solution
Did not copy the token	Cannot be retrieved	Revoke the existing instance and create a new one.
docker compose up succeeded but nothing in lsvrlist	(a) GIIP_ENABLE_AGENT=false (b) GIIP_SK empty (c) first poll not yet due (d) 401 auth error	Check /work/giipAgentLinux/log/cron.log in docker logs for 401 errors
New lssn assigned on every restart	/work volume is ephemeral	Verify docker-compose.yml volume maps to giip-fde-agent-data:/work (entire /work persisted)
[Provision now] fails	Bootstrap script owner mismatch	Use Method ① (manual docker compose up). Token remains valid.
Slack bot not starting	Both SLACK_BOT_TOKEN and SLACK_APP_TOKEN are required	Having only one causes the bot to be skipped entirely.
Immediately redirected to home	uLevel below 70	Log in with an admin account (level 70+).

---

Version: 1.0 Last updated: 2026-09-22 (giip #2847) Source file: giipv3/public/help/docker-instances.en.md