Docker Deployment on Raspberry Pi

The multi-stage, multi-architecture image builds with Node and serves static files through unprivileged-exposed Nginx port 8080. Compose binds it to loopback port 8787 by default.

The docs container is a separate static Nginx service. Its Compose file publishes Nginx only to a configurable loopback port, declares no external network, and leaves the host’s existing reverse proxy and TLS owner unchanged. This design makes the new service an upstream target rather than a replacement for any application already running on the Raspberry Pi.

The practical starting point is to inspect docker ps and listening sockets; do not stop or edit existing services. Continue through the workflow until you for updates, rebuild this service only and retain the previous image tag for rollback, then use the field notes below to understand which choices affected AI output and which only changed delivery, access, or presentation.

What this feature does and when to use it

Deploy behind the Raspberry Pi’s existing reverse proxy and TLS configuration without claiming public ports, joining networks, or modifying other containers.

Use this feature in the following situations:

• You are deploying the built documentation beside existing Raspberry Pi services.
• The default loopback port is occupied and you need to select another without moving anything else.
• You need a resource-limited, read-only static container with a health check and rollback path.

Choose the right feature

Do not run this Compose project with another application’s project name, bind host ports 80/443, or attach to private application networks without an owner-reviewed reason.

Where to find it

WordPress locationRaspberry Pi host → smartsite-assistant-docs directory

Before you begin

• Docker Engine with Compose v2 on the Raspberry Pi.
• An inventory of existing containers, networks, and listening ports.
• An unused loopback TCP port selected by the operator.
• Access to add one route in the existing reverse proxy for smartsite.markomalec.com; keep existing TLS ownership unchanged.

Set it up step by step

1. Inspect docker ps and listening sockets; do not stop or edit existing services.
2. Copy/clone only the documentation project to its own directory.
3. Choose an unused loopback port in a local .env, such as SMARTSITE_DOCS_PORT=8787.
4. Run docker compose build, then docker compose up -d for this compose project.
5. Confirm the container health and curl http://127.0.0.1:8787/.
6. Add a host route in the existing reverse proxy to that loopback URL, preserving its TLS/network conventions.
7. Verify https://smartsite.markomalec.com, search, 404, sitemap-index.xml, and headers.
8. For updates, rebuild this service only and retain the previous image tag for rollback.

Fields, controls, and important values

These container settings only affect how the static documentation is served. They cannot change plugin behavior or AI output. Their purpose is to keep the guide available without occupying existing ports, networks, proxy ownership, or excessive Raspberry Pi resources, so administrators can reliably reach the instructions used to configure the assistant.

Fields, controls, and important values

Field, control, or status	What SmartSite Assistant does with it	How to use it and why it matters
Loopback bind	127.0.0.1:${SMARTSITE_DOCS_PORT:-8787}:8080; no public 80/443 bind.	Publishing only to the loopback address gives the existing reverse proxy a private upstream without claiming public ports. Choose an unused host port and leave external TLS and hostname routing with the service that already owns them.
Networks	No custom/external Docker network is declared.	The Compose project declares no shared or external network, which reduces accidental reach into other applications. Add connectivity only for a documented need and never attach the static documentation container to private WordPress or database networks for convenience.
Isolation	read_only, tmpfs runtime paths, no-new-privileges, dropped capabilities with only Nginx startup capabilities restored.	Read-only filesystems, temporary writable paths, dropped privileges, and limited startup capabilities reduce what a compromised static server can change. Recheck these protections whenever the base image or Nginx startup requirements change.
Resources	128 MB memory and 0.50 CPU Compose limits.	The CPU and memory limits keep a small static documentation service from competing heavily with other Raspberry Pi workloads. Monitor the real device after launch and adjust only this Compose project if indexing or traffic shows sustained pressure.
Health	HTTP GET to loopback port 8080 every 30 seconds.	Configure “Health” from the receiving system’s documented contract, including method, headers, and expected response. It can deliver data used in an answer or action, but it cannot make an unsafe destination trustworthy.

How to confirm it is working

Success looks like

Only the new loopback port/container is added, existing services remain unchanged, health is passing, and the existing proxy serves the canonical HTTPS hostname.

Judge Docker Deployment on Raspberry Pi where its effect is actually consumed—by the administrator, visitor, model, or connected service. The expected result above is more useful than a green badge because it describes the behavior the configuration was meant to produce.

Practical example

If 8787 is used, set SMARTSITE_DOCS_PORT=8788 after confirming it is free; do not move an existing container.

Recommended practice

• Change one part of Docker Deployment on Raspberry Pi at a time and keep a short record of the previous value and test result.
• Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.

Important warnings

Before using this in production

• Never run docker compose down outside this project directory or with another project name.
• Do not bind 80/443, replace the proxy, create a competing TLS service, or attach to an existing application network without owner approval.
• The compose file contains no secrets; do not add API keys.

Common problems and focused checks

Common problems and focused checks

Problem	What to check and what to do next
Docker Deployment on Raspberry Pi is missing or does not match this guide.	Confirm the plugin is active and the account can manage WordPress options. Regenerate source-derived files and run the complete documentation validation before publishing the result.
A change on Docker Deployment on Raspberry Pi does not produce the expected result.	Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Regenerate source-derived files and run the complete documentation validation before publishing the result.

Commands

Read-only preflight

docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Status}}'
ss -ltn

Deploy only this project

cd smartsite-assistant-docs
cp .env.example .env
docker compose build
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8787/

Rollback pattern

docker image ls smartsite-assistant-docs
# Set the previously retained image tag in compose, then:
docker compose up -d --no-deps smartsite-assistant-docs

Screen reference

operations-docker-deployment

Screenshot capture pending /images/screenshots/operations/docker-deployment.webp

Docker Deployment on Raspberry Pi

Capture

Show docker compose ps for only smartsite-assistant-docs and a successful loopback curl; redact hostnames/IPs other than 127.0.0.1.

Show

Container name, image, healthy state, 127.0.0.1 port mapping, HTTP 200

Viewport

Desktop, 1440 × 900

Annotate

Use numbered callouts only for controls referenced in the procedure.

Redact

OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text

Related guides

• Local authoring
• Update documentation