Puter docker container cannot start, write to /var/puter

[mfrancisbeehive]

Issue Description

Docker compose not working on Mac. Says it cannot write to /var/puter

Steps to Reproduce

1. Create a new directory to hold puter files
2. Change to the directory
3. Paste and run the commands from the README for Docker Compose on Mac/Linux

Expected & Actual Behavior

Puter should start and run as normal

Addition Information or Screenshots (if applicable)

Deployment

• [ ] Production (puter.com)
• [ ] Development (npm run start)
• [ ] Docker (via docker run)
• [x] Docker (via docker-compose)

Puter version (if accessible)

Latest as of this issue submission

[KernelDeimos]

Hello, I'm not able to reproduce this issue. Please ensure you're running docker compose up in the correct directory - a directory containing a subdirectory puter with the sub-directories data and config.

Also you may want to know that running with docker compose currently comes with a disadvantage. The development console gets completely obliterated by Docker and you will be unable to get the password for the admin user or run any dev console commands.

[Roi-Danton]

I have the same problem. Did a fresh installation.

There are two options described how to do puter with docker. None of them worked for me.

[DevBengel]

Same here- i mounted two new docker volumes to puter. Same result. Its a permission issue. If you really chown the directories and/or volumes like stated (chown -R 1000:1000 puter) you are allowed to write. This is just a workaround in my opinion...

Best regards

[Roi-Danton]

Nope, this doesn't work for me. I tried every right I know. The UID 1000 is set in the yml file right? Because 1000 is another user for me. Not the one running the container.

[dennysubke]

Same here- i mounted two new docker volumes to puter. Same result. Its a permission issue. If you really chown the directories and/or volumes like stated (chown -R 1000:1000 puter) you are allowed to write. This is just a workaround in my opinion...

Best regards

Didn't work for me... It's frustrating.

[dennysubke]

I want to install Puter on my umbrel home server using docker-compose. All configurations were carried out as described in the docs. Umbrel can be reached via the address umbrel.local. Unfortunately after the installation I get the following screen:

I mounted the config in the following directory: ${APP_DATA_DIR}/config:/volatile/config A config.json was not generated. So I added it with the following content:

{
  "server_id": "umbrel.local",
  "http_port": "4100",
  "domain": "umbrel.local",
  "pub_port": "4100"
}

Nevertheless, I get the error message from the screen above, even though according to the logs everything should be fine. The username and password are also generated.

Here the docker-compose.yml can be found from my repository.

I've already tried a lot, but I've now reached the end. There has to be a solution?!?! I would be grateful for any help or ideas. 😎

@KernelDeimos , maybe you?

[KernelDeimos]

I see some of you were observing the output in a terminal, which tells me you were running the Docker container on a local machine. I would recommend for local running to just use node. The docker container rarely works properly for anyone, and we don't use it ourselves. It has been more painful to attempt to support Docker than it has been to support Windows, and I say that while knowing the server likely doesn't currently run under Windows.

As for @dennysubke I think you brought this up in a separate issue and we're handling it there - can you confirm? (we had a bit of backlog, so I'm going through all the issues again)

[arkilis]

@mfrancisbeehive @KernelDeimos @dennysubke @Roi-Danton @DevBengel I tried sudo chmod -R 777 puter, it works

[dennysubke]

@arkilis Thanks for your hint. Doesn't work for me. This has already been discussed elsewhere. It is definitely a problem in the docker container.

[VirajSingh19]

can we update the docs to sudo chmod -R 777 puter ?

[KernelDeimos]

@arkilis Thanks for your hint. Doesn't work for me. This has already been discussed elsewhere. It is definitely a problem in the docker container.

That was a non-sequitur. If you believe there's an issue in the docker container then you must have more information you can provide to us to help us resolve the issue, right?

[KernelDeimos]

can we update the docs to sudo chmod -R 777 puter ?

We could, and it would work for more people, but that's not actually the right solution. The docker container is supposed to be deterministic, so it's strange that the uid of 1000 isn't consistent for everyone. Someone needs to provide more information if we're to resolve this issue; as it is now, there's nothing useful we can do because we simply don't have the information. Docker container works fine for me, so I can't reproduce the issue to further diagnose it myself.

[LittleNewton]

I cannot accept sudo chmod -R 777 puter. It is totally not secure!

[LittleNewton]

And I don't think making /var/puter writable is a good idea.

# Author: Peng Liu
# Email: [email protected]
# Created: 17 Oct. 2025
# Updated: 17 Oct. 2025
# Official Release: https://github.com/HeyPuter/puter

services:
  puter:
    container_name: puter
    image: ghcr.io/heyputer/puter:latest
    pull_policy: always
    # build: ./
    restart: unless-stopped
    ports:
      - '4100:4100'
    environment:
      TZ: Asia/Shanghai
      CONFIG_PATH: /etc/puter
      PUID: 1000
      PGID: 1000
    volumes:
      - ${APPDATA_PATH}/Puter:/etc/puter
      - ${NAS_DOC_PATH}:/var/puter/Documents:ro
      - ${NAS_SOFTWARE_PATH}:/var/puter/Software:ro
      - ${NAS_DROPBOX_PATH}:/var/puter/Dropbox:ro
      - ${NAS_DOWNLOADS_PATH}:/var/puter/Downloads:ro
      - ${NAS_MEDIA_PATH}:/var/puter/Media:ro
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://puter.localhost:4100/test || exit 1
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 30s

I just want a simple file browser, so read-only is the best choice.