chore: update Dockerfile for homeserver build with entrypoint script by francismars · Pull Request #299 · pubky/pubky-core

francismars · 2026-01-19T14:40:25Z

Summary

Updates the Dockerfile for homeserver builds and adds an entrypoint script for configuration management and security.

Changes

Dockerfile Updates

Build target: Changed default BUILD_TARGET from testnet to homeserver
Runtime dependencies: Added wget, netcat-openbsd, and su-exec for healthchecks and user switching
Security: Created non-root user homeserver (UID/GID 1000) to match Umbrel's default
Port exposure: Updated to expose all required ports:
- 6286 - HTTP (ICANN)
- 6287 - Pubky TLS
- 6288 - Admin
- 6289 - Metrics
Working directory: Changed from /usr/local/bin to /data for persistent data storage

New Entrypoint Script (`entrypoint.sh`)

Automatic configuration: Generates config.toml with sensible defaults if it doesn't exist
Environment variable support: Configures database connection and admin password from environment variables
Security: Ensures proper file permissions and ownership before switching to non-root user
User switching: Uses su-exec to run the homeserver as the homeserver user
Data directory: Runs homeserver with --data-dir /data flag

Benefits

Security: Runs as non-root user, reducing attack surface
Umbrel compatibility: User/group IDs match Umbrel's defaults (1000:1000)
Easier deployment: Automatic configuration generation reduces manual setup
Production-ready: Proper port exposure and healthcheck support

Testing

Docker image builds successfully
Container starts and generates config.toml correctly
Homeserver runs as non-root user
All ports are accessible
Environment variables are properly injected into config

- Change default build target from testnet to homeserver. - Install additional runtime dependencies: wget, netcat, and su-exec. - Create a non-root user for homeserver. - Update port exposure to include HTTP, Pubky TLS, Admin, and Metrics. - Implement entrypoint script for handling configuration and user switching.

SHAcollision

Hey @francismars great work! Nice to see the homeserver and the dashboard fully functional on Umbrel. 💪

I left some comments and some requests for changes.

Dockerfile

entrypoint.sh

SHAcollision · 2026-01-20T08:57:46Z

entrypoint.sh

+mkdir -p /data
+
+# Generate config.toml if it doesn't exist
+if [ ! -f /data/config.toml ]; then


Just a comment for further reference: copying an entrypoint.sh into the image that has a hardcoded configuration feels somewhat unorthodox. But it it works, it works, so let's keep it this way for now.

I guess the cleanest way would be to mount /data/config.toml (adding the default config.toml here) and implement into the homeserver the ability to read/interpolate the missing values form the env vars. Maybe let's explore this in the future. @SeverinAlexB what do you think?

SHAcollision · 2026-01-20T08:58:18Z

entrypoint.sh

+[general]
+signup_mode = "token_required"
+user_storage_quota_mb = 0
+database_url = "postgres://pubky:${POSTGRES_PASSWORD}@postgres:5432/pubky_homeserver"


Out of curiosity what is the value that Umbrel feeds here ${POSTGRES_PASSWORD} , is it secure?

According to the Umbrel Apps documentation, APP_PASSWORD is described as:

"$APP_PASSWORD - Unique plain text password that can be used for authentication in your app, shown to the user in the Umbrel UI"

Can you take a look, on your running Umbrel container's /data/config.toml to verify that this is a strong and randomly generated password?

Verified: the admin password is a 64-character hexadecimal string.

SHAcollision · 2026-01-20T09:45:42Z

entrypoint.sh

+public_ip = "127.0.0.1"
+icann_domain = "localhost"


This configuration will not result in a working homeserver for the user. This should be the real user IP address. Ideally, if the user wants the homeserver accessible from browsers, also would need an ICANN domain.

The entrypoint now detects configuration values:

Uses PUBLIC_IP environment variable if set

Otherwise attempts to auto-detect local IP via hostname -i

Falls back to 127.0.0.1 with a warning if detection fails

For icann_domain:

Uses ICANN_DOMAIN environment variable if set

Otherwise uses Umbrel's DEVICE_DOMAIN_NAME as a better default

Falls back to localhost with a warning if neither is available

I guess the only way forward to make this useful for a final user is to create and link an installation guide telling the user how the homeserver needs to be configured: e.g. NAT transversal should be configured correctly (firewall and ports forwarding) and if you want to use the HS from a browser, an ICANN domain is needed currently.

Added a section in the Umbrel deployment README covering external access and PKARR configuration

- Change default build target from homeserver to testnet. - Remove unnecessary runtime dependencies and user creation. - Update port exposure to only include the homeserver port. - Set the default command to run the homeserver binary.

- Introduced a multi-stage Dockerfile for building and running the Umbrel homeserver. - Added an entrypoint script to handle configuration generation and user permissions. - Configures necessary environment variables and ensures required directories and files are created at runtime.

- Introduced a comprehensive README file detailing the Umbrel-specific Docker configuration for the Pubky Homeserver. - Included sections on building the Docker image, required and optional environment variables, configuration details, exposed ports, and security considerations. - Clarified differences from the generic Dockerfile to enhance understanding for users deploying on Umbrel.

…yment - Modified the Dockerfile to copy the entrypoint script to a temporary location, fix line endings to ensure compatibility with Unix systems, and then move it to the final destination. - This change ensures the entrypoint script functions correctly regardless of the line endings in the source repository.

- Deleted the entrypoint.sh script as it is no longer needed for the Umbrel deployment. - This change simplifies the Docker configuration and reduces maintenance overhead.

SHAcollision

Nice, the changes look good to me!

We likely also want to add a new PR-check to verify we don't break this docker image. We could add one more step similar to this one for docker-umbrel-build

pubky-core/.github/workflows/pr-check.yml

Lines 266 to 271 in 0ec564d

    
           docker-build: 
        
             runs-on: ubuntu-latest 
        
             steps: 
        
               - uses: actions/checkout@v4 
        
               - name: Build Docker image 
        
                 run: docker build .

…uctions - Added a section detailing the configuration for external access and PKARR, including environment variable setup and infrastructure requirements. - Provided clear steps for users to configure NAT traversal, firewall rules, and DNS settings for production deployments.

- Introduced a new job in the GitHub Actions workflow to build the Umbrel Docker image. - This job runs on the latest Ubuntu environment and utilizes a specific Dockerfile for the Umbrel deployment.

francismars · 2026-01-26T12:47:36Z

Added the docker-umbrel-build job to .github/workflows/pr-check.yml

- Included a new section in the README for deploying on Umbrel OS. - Added a link to the Umbrel deployment guide, which contains a specialized Dockerfile and entrypoint script for automatic configuration.

francismars · 2026-01-26T12:51:06Z

Added a reference to the Umbrel deployment in the root README under the Docker section

SHAcollision

LGTM! I'd like @SeverinAlexB and @SpontaneousOverthrow to also confirm this looks OK for them before merging (regarding keeping this repo tidy and regarding mantaining docker image registry for external users).

ok300

Added some thoughts on a few edge-cases.

deployments/umbrel/Dockerfile

deployments/umbrel/entrypoint.sh

- Added ARG TARGETARCH to the Dockerfile to allow for building images for different architectures using Docker Buildx. - This change enhances compatibility for users deploying on various platforms.

…on management - Updated the Dockerfile to include gettext for environment variable substitution. - Added a config template to the Docker image for dynamic configuration generation. - Modified the entrypoint script to utilize envsubst for safely substituting environment variables into the config file, improving flexibility and preventing syntax errors.

SeverinAlexB · 2026-01-28T11:12:35Z

ACK from a pubky-core structure POV. It's important to have CI fail in case something doesn't work as expected. This makes sure we recognize one of our changes will make Umbrel unusable.

No opinion on implementation details. That's up to you guys.

- Added concurrency settings to cancel outdated runs, optimizing CI minutes. - Implemented permissions for content and checks in the workflow. - Introduced validation steps to ensure required template files and placeholders exist before building the Docker image. - Added syntax validation for the entrypoint script to catch errors early in the CI process. - Updated the Docker build step to tag the image appropriately and verify required files are included in the final image.

francismars · 2026-01-29T03:33:02Z

Thank you @SeverinAlexB! Added CI checks for Umbrel deployment (template validation, entrypoint syntax, Docker build, file verification). Also improved CI efficiency with concurrency control, explicit permissions, and build timeouts

- Added support for reading the domain from a Cloudflare configuration file, allowing for dynamic domain assignment. - Updated logic to prioritize Cloudflare domain over environment variables for ICANN_DOMAIN detection. - Improved warnings for default values that may not work for external access, emphasizing Cloudflare usage. - Ensured the config file is updated with Cloudflare settings if already present, enhancing configuration management.

francismars changed the title ~~Main~~ chore: update Dockerfile for homeserver build with entrypoint script Jan 19, 2026

SHAcollision requested changes Jan 20, 2026

View reviewed changes

SHAcollision reviewed Jan 20, 2026

View reviewed changes

francismars added 6 commits January 22, 2026 16:39

chore: reverted Dockerfile for testnet build

a6288d5

- Change default build target from homeserver to testnet. - Remove unnecessary runtime dependencies and user creation. - Update port exposure to only include the homeserver port. - Set the default command to run the homeserver binary.

refactor: remove entrypoint script from repository

34b7e50

- Deleted the entrypoint.sh script as it is no longer needed for the Umbrel deployment. - This change simplifies the Docker configuration and reduces maintenance overhead.

fix: ensure newline at end of Dockerfile for consistency

80ae86f

SHAcollision requested changes Jan 25, 2026

View reviewed changes

francismars added 2 commits January 26, 2026 12:41

feat: add Docker build job for Umbrel image in CI workflow

d912f9a

- Introduced a new job in the GitHub Actions workflow to build the Umbrel Docker image. - This job runs on the latest Ubuntu environment and utilizes a specific Dockerfile for the Umbrel deployment.

docs: add Umbrel deployment section to README

abcef04

- Included a new section in the README for deploying on Umbrel OS. - Added a link to the Umbrel deployment guide, which contains a specialized Dockerfile and entrypoint script for automatic configuration.

SHAcollision previously approved these changes Jan 27, 2026

View reviewed changes

ok300 reviewed Jan 27, 2026

View reviewed changes

deployments/umbrel/Dockerfile Outdated Show resolved Hide resolved

deployments/umbrel/entrypoint.sh Outdated Show resolved Hide resolved

fix: update Dockerfile to support multi-architecture builds

7098c20

- Added ARG TARGETARCH to the Dockerfile to allow for building images for different architectures using Docker Buildx. - This change enhances compatibility for users deploying on various platforms.

francismars dismissed SHAcollision’s stale review via 7098c20 January 27, 2026 17:23

	docker-build:
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4
	- name: Build Docker image
	run: docker build .

		public_ip = "127.0.0.1"
		icann_domain = "localhost"

Comments

Conversation

francismars commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Dockerfile Updates

New Entrypoint Script (entrypoint.sh)

Benefits

Testing

Uh oh!

SHAcollision left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SHAcollision left a comment

Choose a reason for hiding this comment

Uh oh!

francismars commented Jan 26, 2026

Uh oh!

francismars commented Jan 26, 2026

Uh oh!

SHAcollision left a comment

Choose a reason for hiding this comment

Uh oh!

ok300 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

SeverinAlexB commented Jan 28, 2026

Uh oh!

francismars commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

francismars commented Jan 19, 2026 •

edited

Loading

New Entrypoint Script (`entrypoint.sh`)