Skip to content

IT-Tools ​

IT-Tools provides browser utilities such as JSON formatting and UUID generation. It is stateless and has no application database or NAS dependency.

Prepare the guest using the host setup guide. Host-specific AI commands and private recovery details are in IT-Tools · Internal Operations.

Access and configuration ​

SettingThis homelab
Host address10.120.40.100
Domaintools.home.rwk.me
Normal accesshttps://tools.home.rwk.me
Direct accesshttp://10.120.40.100:8080
Project directory/docker/it-tools

For another homelab, use your own host address, domain, timezone, paths, and network policy. The addresses above describe internal access; the dashboard does not require a public router port forward.

Create the project ​

Run as a deployment account with Docker access on the prepared guest:

sh
sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0750 /docker/it-tools
cd /docker/it-tools

Create compose.yaml with the following configuration. It is a documented example of the repository's pinned deployment, not a second deployment source file:

yaml
name: it-tools

services:
  it-tools:
    image: homelab/it-tools:local
    build: .
    pull_policy: never
    container_name: it-tools
    ports:
      - "${SERVER_IP:?Set SERVER_IP in .env}:8080:80"
    security_opt:
      - no-new-privileges:true
    mem_limit: 256m
    cpus: 0.5
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    restart: unless-stopped

Create .env alongside it:

dotenv
SERVER_IP=10.120.40.100

Replace blank secrets and example credentials before starting. SERVER_IP must be an address assigned to the Docker host. Preserve existing keys and data when updating an installation. Protect the file with chmod 600 .env and keep it out of Git.

Build the web runtime ​

Create Dockerfile next to Compose:

dockerfile
# Keep the released application assets while refreshing the web-server runtime.
FROM corentinth/it-tools:2024.10.22-7ca5933@sha256:8b8128748339583ca951af03dfe02a9a4d7363f61a216226fc28030731a5a61f AS upstream

FROM nginx:1.31.8-alpine@sha256:1ef7ca94d7879df82421428ce13bd1eaa412404953859cf7a5b6512c25e67a60
# Apply Alpine security fixes published since the base image was built.
RUN apk upgrade --no-cache
COPY --from=upstream /usr/share/nginx/html /usr/share/nginx/html
COPY --from=upstream /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf

Create .dockerignore containing:

text
*
!Dockerfile

The build copies released frontend assets into a maintained Nginx image and applies available Alpine package fixes. Updating the runtime does not update the frontend release; review both image references. The build is local, and its output is not pushed to a registry.

Start and verify ​

Run only this Compose project:

sh
cd /docker/it-tools
docker compose config --quiet
docker compose build --pull --no-cache
docker compose up -d --no-build --wait --wait-timeout 120
docker compose ps
docker compose logs --tail=100 it-tools

Keep logs private. Do not rerun the base guest provisioner to install or update one service; it upgrades the host and restarts Docker.

Configure DNS and HTTPS ​

Make tools.home.rwk.me resolve to Nginx Proxy Manager (10.120.40.101 in this lab). Add a proxy host:

SettingValue
Domaintools.home.rwk.me
Schemehttp
Backend10.120.40.100
Port8080
WebSocketsNot required
CertificateA certificate covering tools.home.rwk.me
Force SSL / HTTP/2Enabled

Use your own domain and certificate on another homelab. Apply a LAN/VPN access list appropriate to your users. A proxy access list does not restrict clients connecting directly to a backend port; use network filtering when the backend must be proxy-only.

Check both paths:

sh
curl --fail --silent --show-error --output /dev/null http://10.120.40.100:8080/
curl --fail --silent --show-error --output /dev/null https://tools.home.rwk.me/

Add the HTTPS page to Uptime Kuma, using TLS validation and a suitable check interval. Monitoring on the same VM cannot independently report that VM's outage.

Use the tools ​

Open the HTTPS dashboard, select a tool, and test representative functions such as JSON formatting and UUID generation. Refresh a deep URL such as /json-prettify to verify frontend routing. HTTPS also enables browser features restricted on plain HTTP.

Maintenance and recovery ​

There is no persistent database to archive. Preserve Compose, the Dockerfile, and the exact previous built image. docker compose pull alone does not rebuild this service. For an update, rebuild and run up -d --no-build --wait; for rollback, restore the previous image/configuration and use --no-build. Do not prune the retained image before the new build is proven. The lab automates reviewed builds through the operations runner.

The deployed files remain in the private homelab source directory. Keep these instructions aligned with source changes. Review release notes and preserve a recovery point before updating pinned images. After maintenance, repeat the checks and verify the main application function.