Skip to content

feat: add rootless dev docker scripts#44

Open
CjS77 wants to merge 1 commit intobitcart:masterfrom
grease-xmr:dev-docker
Open

feat: add rootless dev docker scripts#44
CjS77 wants to merge 1 commit intobitcart:masterfrom
grease-xmr:dev-docker

Conversation

@CjS77
Copy link

@CjS77 CjS77 commented Mar 18, 2026

Local development without root - in docker.

The standard Bitcart startup flow is:

setup.sh → Installs Docker, writes system-level config to /etc/profile.d/,
registers systemd services, edits /etc/hosts for .local domains,
and calls start.sh. Must be run as root.

start.sh → Sources helpers.sh, calls load_env (which reads the profile
script from /etc/profile.d/ and the .deploy file), then runs
bitcart_start to build plugins and bring up containers.
Assumes setup.sh has already run.

Both scripts assume root access for:
- Writing to /etc/profile.d/ (environment persistence)
- Binding ports 80/443
- Editing /etc/hosts for .local domains
- Touching files inside Docker volume paths on the host filesystem

Sometimes, root access is not available, or not desirable. This script bypasses all of that:

  • Writes the profile script to a local file (.bitcart-env-dev.sh) instead
    of /etc/profile.d/
  • Uses sslip.io wildcard DNS (*.127-0-0-1.sslip.io → 127.0.0.1) so no
    /etc/hosts editing is needed
  • Binds to high ports (8080/8443) instead of 80/443
  • Manages the .plugins-failed sentinel file via a throwaway container
    instead of touching the Docker volume path directly on the host
  • Applies compose/dev-overrides.yml which adds extra_hosts entries so
    that admin/store containers can reach the API via sslip.io (which
    would otherwise resolve to 127.0.0.1 inside the container)
  • Limits API workers to 2 to avoid exhausting postgres connections
  • Sets all deployment config as env vars (not in .deploy) so they
    survive save_deploy_config overwriting .deploy

Usage

./dev-start.sh # start/restart the stack
./dev-stop.sh # stop the stack

After startup

Service URL
API http://api.127-0-0-1.sslip.io:8080/
Admin http://admin.127-0-0-1.sslip.io:8080/
Store http://127-0-0-1.sslip.io:8080/

- dev-start.sh: starts the Bitcart stack without requiring root access,
  using sslip.io wildcard DNS on high ports (8080/8443) instead of
  .local domains on port 80
- dev-stop.sh: stops the dev stack
- compose/dev-overrides.yml: extra_hosts entries so SSR requests from
  admin/store containers reach the API via the Docker host
- .gitignore: add var/ for local static sites directory

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@MrNaif2018
Copy link
Member

MrNaif2018 commented Mar 18, 2026

Thank you/claude, but what is the main purpose of this PR?
Is this to allow deploying bitcart without root - which would require modifying main scripts and not creating new ones

Or deployment in docker, but for what purposes specifically? Local development of e.g. plugins?
It is recommended to deploy via https://docs.bitcart.ai/deployment/manual if you want to develop plugins or contribute fixes, because developing in docker is useless

Otherwise, I don't think I understand why this is needed?

Also this deploy disables one domain mode for some reason
Hardcodes specific cryptos, bypasses env var loading from /etc/profile.d, which is required if you want to re-configure your instance and not loose all env vars already set
sets non-existing (STATIC_SITES_PATH) env vars
overrides workers for some reason

(also admin panel and store now send requests only from browser in optimized use case)
duplicates plugin build code
and more

@CjS77
Copy link
Author

CjS77 commented Mar 19, 2026

You're right in that it's mostly useful for developing/testing plugins. Bitcart is flexible enough that it makes sense to leave the base platform as is, and make all desired changes via plugins.

However, I found setting up a dev environment very cumbersome:

  • My dev environment is locked down, so there's no access to root.
  • A full bitcart deployment has a large number of moving parts, as you know. The manual deployment is simply not an option -- especially since the particular plugin I was testing modified nginx configurations.

A local docker environment is very simple. start.sh and stop.sh equivalents, although the existing scripts won't work locally.

tl;dr almost all the existing deployment options need root, or are very difficult to orchestrate or both.

So these scripts let you spin up a test environment for installing and testing plugins. You have to do the full plugin install, or mount the plugin folders yourself (symlinks don't work), but I don't mind the former, since it's a full e2e test and it's easily automated via the REST api.

I pushed the PR because I found these scripts very useful and others may find value in it.

@MrNaif2018
Copy link
Member

especially since the particular plugin I was testing modified nginx configurations.

How is that possible?

Also don't you loose hot reload during development then?
It is supposed that plugins (backend/admin) is developed alongside the main apps to be able to re-use the same e.g. formatting, linting and checking tools, and to verify some stuff without even running the plugins

@CjS77
Copy link
Author

CjS77 commented Mar 19, 2026

As I said, I didn't mind not having hot reloading, since the loop is fairly tight.

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.

2 participants