Skip to content

improvement: better docker builds#1098

Open
kjagosz wants to merge 1 commit intotobychui:v3.3.3from
kjagosz:pr/feat-better-docker
Open

improvement: better docker builds#1098
kjagosz wants to merge 1 commit intotobychui:v3.3.3from
kjagosz:pr/feat-better-docker

Conversation

@kjagosz
Copy link
Copy Markdown
Contributor

@kjagosz kjagosz commented Mar 30, 2026

This PR focuses on improving Docker build performance and restructuring how ZeroTier integration is handled in the project.

The main idea was to make builds faster and cleaner while decoupling ZeroTier from the core image, without breaking existing behavior.

What was changed

  • Optimized Docker build process to reduce build time and improve layer caching
  • Separated ZeroTier-related logic from the main Zoraxy build flow
  • Introduced configuration flags to control whether ZeroTier is included
  • Kept default behavior unchanged (ZeroTier still enabled by default)

New workflow variables

Added new variables in .github/workflows/docker.yml to control build behavior:

  • DOCKER_MAIN_IMAGE_WITH_ZEROTIER
    Controls whether the main image includes ZeroTier (default: true)
  • DOCKER_BUILD_ZEROTIER
    Enables building ZeroTier-specific layers/images (default: true)
  • DOCKER_REPO_TAG_CACHE_NAME_BASE
    Cache tag used for base image layers to speed up rebuilds
  • DOCKER_REPO_TAG_CACHE_NAME_ZEROTIER
    Separate cache tag for ZeroTier-related layers
  • DOCKER_PLATFORMS
    Defines target platforms for buildx (e.g. linux/amd64,linux/arm64)

These variables allow more granular control over builds and significantly improve caching efficiency in CI.

Why

Docker builds were taking longer than necessary and were harder to maintain due to tight coupling between Zoraxy and ZeroTier.

This change:

  • speeds up CI/CD pipelines
  • simplifies the base image
  • makes it easier to maintain and extend the project in the future

At the same time, backward compatibility was preserved so existing users don’t notice any difference after updating.

Backward compatibility

No breaking changes.

By default:

  • ZeroTier is still included
  • behavior remains identical to previous versions

Users who don’t need ZeroTier can now disable it and get a lighter build.

Open question / discussion

This PR also opens a design question:

Should ZeroTier remain part of the main repository, or be moved to a plugin/extension model?

Things to consider:

  • keeping it in core → simpler UX, one image “just works”
  • moving to plugin → cleaner architecture, smaller base image, more flexibility

Would be good to align on direction before expanding further in this area.

@kjagosz kjagosz marked this pull request as draft March 30, 2026 19:17
@kjagosz kjagosz changed the base branch from main to v3.3.3 March 30, 2026 19:18
@kjagosz kjagosz marked this pull request as ready for review March 30, 2026 19:19
@PassiveLemon
Copy link
Copy Markdown
Collaborator

So far looks promising, but I'll have to take a more detailed look at it tomorrow before I approve. I'm really wondering now if we should completely redo the docker build workflow. It's getting very very cluttered with all the environment variables and is nearly unreadable

Should ZeroTier remain part of the main repository, or be moved to a plugin/extension model?

I have a few words about this. On one hand, Zoraxy already has first-party plugin support for ZT so I think it's appropriate that the Docker users aren't left out, but on the other hand I don't use it (Or even Zoraxy for that matter) and don't have any testing procedures for it other than making sure networks can be created, edited, and removed without issue. Moving it to an external plugin repository would probably allow for more direct contribution from those who actually use it rather than needing me to audit all changes

Copy link
Copy Markdown
Collaborator

@PassiveLemon PassiveLemon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, just some information I would like to help me understand some changes a little better before it gets merged


global zoraxy_proc

mdns_name = getenv("MDNSNAME", "''")
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could we remove this? it doesn't appear to do anything

WORKDIR /opt/zoraxy/source/

RUN go mod tidy &&\
RUN --mount=type=cache,target=/go/pkg/mod \
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We already build in stages and Zoraxy is only built once, what is this for?


RUN apk add --update --no-cache curl make gcc g++ linux-headers openssl-dev nano

RUN --mount=type=cache,target=/root/.cargo/registry \
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again here, what is this for?

Additionally, the Zoraxy build stage in this Dockerfile looks the same as in the normal Dockerfile. Shouldn't need to also build it here

@tobychui
Copy link
Copy Markdown
Owner

tobychui commented Apr 5, 2026

Hey @kjagosz , would you like to make those changes yourself or I will help you to remove those line @PassiveLemon commented and consider unnecessary?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants