Docker for local environment

[ceinstaller]

Hey all, I've been trying most of the day to get paperclip running locally. I have a dedicated docker server that I'd like to have it running on, accessible from my local network. Can someone help get a docker command going that will spin up Paperclip, that's accessible from my home network, that's not tied to a domain? I just want to spin up the container, get the secret invite, go to http://10.0.0.X:3000/invite/XXXX, create an account using my business email and get going.

I started with cloning the repo and trying to use the docker compose files, but I always run into a roadblock. I switched to published container thinking that would be easier, but still no luck. Here's what I've been trying:

docker run -d \
  --name paperclip \
  -p 3100:3000 \
  -p 3101:3001 \
  -v /home/user/paperclip/data:/data \
  -e BETTER_AUTH_SECRET="my-paperclip-secret-key" \
  -e PAPERCLIP_DB_URL="sqlite:///data/paperclip.db" \
  ghcr.io/paperclipai/paperclip:latest

I've tried the docs, searching, and I just can't seem to get it so that I can create an account from a workstation on my local network, create an account and get up and running. I don't need an enterprise ready, highly secure setup. I'm just playing around at home.

Thanks in advance!

[cookesan]

The Docker command you sketched is using the wrong container-side shape for the documented setup. Paperclip's Docker docs and quickstart compose file expose the app on container port 3100, keep the app data under /paperclip, and set HOST=0.0.0.0.

For a LAN-only test I would either use the documented compose quickstart, with the public URL changed to the address you will actually open in the browser:

BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
PAPERCLIP_PUBLIC_URL="http://10.0.0.X:3100" \
docker compose -f docker/docker-compose.quickstart.yml up --build

or mirror the documented one-container command:

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -e PAPERCLIP_PUBLIC_URL=http://10.0.0.X:3100 \
  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
  -v "$PWD/data/docker-paperclip:/paperclip" \
  paperclip-local

Then open http://10.0.0.X:3100, not port 3000. I would avoid -p 3100:3000, -p 3101:3001, /data, and PAPERCLIP_DB_URL unless a maintainer confirms those apply to the image you are running; they do not match the current Docker docs/compose file.

[ceinstaller]

Thanks for the reply, cookesan. This path leads me to the same dead end. Following your instructions, I can spin up the container, but when I open 10.0.0.X:3100, I get this message:

Hostname '10.0.0.X' is not allowed for this Paperclip instance. If you want to allow this hostname, please run pnpm paperclipai allowed-hostname 10.0.0.X

I'm using Portainer, so I go to the papreclip container, open a shell and run the requested command:

Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.15.4.tgz Do you want to continue?

I say yes, it does what it needs to do and then runs the command again, with this output:

No config found at /paperclip/instances/default/config.json. Run paperclip onboard first.

While still in the console I try to run 'paperclip onboard' but there is no paperclip command to run:

bash: paperclip: command not found

I've tried to use 'find' to see if there's a way to run 'paperclip' in the console but there doesn't appear to be. At this point I'm stuck. If I look in the host data directory I can see that it created a directory structure, but there's no config.json to add my local IP to.

Thoughts?

[cookesan]

That error is the config-backed CLI path crossing with the env-backed Docker path.

In the production Docker image, the container starts the server directly with node ... server/dist/index.js; it does not run paperclipai onboard, so there may be no /paperclip/instances/default/config.json for paperclipai allowed-hostname to edit. The server config does still read hostnames from environment: PAPERCLIP_ALLOWED_HOSTNAMES, and the hostname portion of PAPERCLIP_PUBLIC_URL.

For Portainer, set the container environment instead, then recreate/restart the container:

PAPERCLIP_PUBLIC_URL=http://10.0.0.X:3100
PAPERCLIP_ALLOWED_HOSTNAMES=10.0.0.X

Use your real LAN IP in both places. PAPERCLIP_ALLOWED_HOSTNAMES should be just the hostname/IP, without http:// and without :3100. If you use the compose quickstart, this is the same issue: its default public URL is http://localhost:3100, so opening the app by LAN IP requires overriding that value.

[ceinstaller]

OK, you were pretty fast, and I didn't see this until after I made some progress! Here's what I did and where I'm at:

'paperclip onboard' was wrong, 'pnpm paperclipai onboard' worked. I selected the quickstart option and it created the config files. (I told it not start start paperclip, as it was already running in my terminal.)

I restarted the container in Portainer, but it threw an error about not being able to write to .env. I looked in the data directory and the new files the quickstart created were owned by root. I did a 'chown -R user:user *' and the container was able to start without errors.

At this point it's still telling me I can't access via my IP, so I went back to the container console in Portainer and ran 'pnpm paperclipai allowed-hostname 10.0.0.X' and restarted the container.

Then it told me there was no CEO, so I went to the console to run 'pnpm paperclipai auth bootstrap-ceo'. I copied the generated link and opened it up. Finally!! I'm now at the 'Set up Paperclip' screen, so I enter my name, email and password. Of course, it's now throwing a 'invalid origin' error when I click 'Create account and continue'.

I'm guessing my issue is related to the server setup in config.json:

  "server": {
    "deploymentMode": "authenticated",
    "exposure": "private",
    "bind": "lan",
    "host": "0.0.0.0",
    "port": 3100,
    "allowedHostnames": [
      "10.0.0.ZZ",
      "10.0.0.x"
    ],
    "serveUi": true
  },
  "telemetry": {
    "enabled": true
  },
  "auth": {
    "baseUrlMode": "explicit",
    "publicBaseUrl": "http://10.0.0.X:3100",
    "disableSignUp": false
  },

Is there a way around the 'invalid origin' error?

Thanks for the help, I really appreciate it. I think got to where you were leading me, just in a more convoluted way, ha!

[cookesan]

That detail changes the env var: it should be PAPERCLIP_PUBLIC_URL, not PAPERCLIP_PUBLIC_ORIGIN.

The Docker docs and compose files use PAPERCLIP_PUBLIC_URL. The quickstart compose file defaults it to http://localhost:3100, so a LAN/Portainer deployment needs that overridden to the exact browser URL you use:

PAPERCLIP_PUBLIC_URL=http://10.0.0.X:3100
PAPERCLIP_ALLOWED_HOSTNAMES=10.0.0.X

Then recreate the container/stack so the server starts with those values. PAPERCLIP_ALLOWED_HOSTNAMES should be just the hostname/IP, without scheme or port.

For the root-owned files, the Docker docs call out USER_UID and USER_GID build args for matching the host user on bind mounts. Your chown fix is the right local repair; for the next rebuild, pass matching UID/GID build args if Portainer allows it. The Docker quickstart is localhost-biased, but it is not inherently limited to localhost once HOST=0.0.0.0, PAPERCLIP_PUBLIC_URL, and allowed hostnames match the LAN URL.

[ceinstaller]

OK, good progress! Using your updates to the docker run command I can now run the onboard and bootstrap-ceo fucntions without error and create my company! Huzzah! The only issue I can't seem to solve is the host files permissions after running the onboard task. I still have to run chown to fix it. Here's the command I'm running:

docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t paperclip-local .

USER_ID and USER_GID match the args in the Dockerfile so I was hoping that would work. I tried to add this to the Dockerfile:

RUN addgroup --gid $USER_GID appgroup && \ adduser --uid $USER_UID --gid $USER_GID --disabled-password --gecos "" appuser

This throws an error about the GID 1000 already being in use. This is as far my research took me and I'm not good enough with Docker to know how to fix it.

I guess I only have to fix permissions once (I hope?), but it would be nice to have it work without the extra step.

At this point I'm in, so now I have to figure out how to point the CEO agent to my hermes agent running on a different computer. Sounds like a good project for tomorrow!

Thanks again for the help, I really appreciate it!

[cookesan]

That points to the shell user, not the Docker build args.

The current Dockerfile already changes the existing node user/group to USER_UID and USER_GID, and the entrypoint runs the server with gosu node "$@". So you do not need to add a second appuser/appgroup; the GID error is from trying to create a new group for an ID that already exists in the image.

The part that can still create root-owned files is the one-off setup command from a container shell. docker exec and Portainer consoles can default to root, which bypasses the entrypoint's final gosu node ... step for that command. Run those setup commands as node instead:

docker exec -it --user node paperclip pnpm paperclipai onboard
docker exec -it --user node paperclip pnpm paperclipai auth bootstrap-ceo

Replace paperclip with your actual container name. If you are already in a root shell inside the container, use:

gosu node pnpm paperclipai onboard

For files already created as root, the host-side chown is still the cleanup step. After that, the setup commands should stop recreating root-owned files as long as they run as node.