Privileged actions on startup

[hughbris]

Preamble: I post this with some trepidation for a couple of reasons:

• I don't know exactly how to classify it or where it should live (issues, feature requests);
• I could very well be missing something and it's easily answered and no kind of issue, or it's a Docker thing.

I think this has been touched on but not answered in a way that helps my situation.

Context: I have derived a flat file CMS image from the upcoming FrankenPHP variation after a few failed attempts in the past, including with a couple of the other variants on offer. This is awesome, I'm pumped! I'm very keen to migrate my package to this base eventually (hopefully soon).

I'm getting there, I promise.

Problem: With no volumes or mounts of any kind, containers stand up and run pretty nicely it seems. I tend to use bind mounts exclusively because I find named volumes a PITA for development and git deployments. When I bind-mount existing host directories, no problems either. The problems start when I want to specify new bind mount directories and start containers.

(The environment is all Linux, FWIW.)

In simple terms, the containers exit because the required filesystems are created on the host with root permissions, and the directories required by the CMS can not be populated with files by a script on container start. As I've learned, this is Docker's documented behaviour for bind mounts, but not for named volumes – Docker creates any non-existing host directories with root privileges where a bind mount is specified. (I would love to know why the two types of persistent storage are initialised differently — there may be good reasons — but it seems it's just "by design" and we are left to shrug our shoulders.)

So the images work fine for existing install mount points but not when creating new ones.

My current images based off official php-fpm base images do not have this problem because the entrypoint script runs privileged. I do like that serversideup have found a way around that still allows me to change GID/UIDs, but I believe this to be the underlying cause of the problem here.

I've experimented a little with different initial host filesystem setups. The only direction I can offer to users to seed a new installation successfully, using my image, is to first create the bind-mounted directories on the host, then set their permissions to the user ID that the container runs as (83, 1000, whatever), and then bring the container up. When I do that, the mount points do get seeded correctly with the files required to run, and persist a working instance of the CMS. However, I don't think that's really a workable requirement or reasonable directive.

Possible suggestion: What would probably work around this without compromising container security is if I could run some commands (like permission setting) at startup. Would it be feasible to create another folder (like /entrypoint.d) or a file naming pattern where I can put startup scripts I want to run as root?

I hope I've been clear here. I'm open to any other suggested solutions or workarounds that don't affect image users' experience. Also happy to clarify anything because I would love to get this working under the new variant.

If this is reasonable, what process do you suggest I follow to progress it?

[jaydrogers]

Thanks for the compliments!

I'm very interested in replicating the problem you reported:

Problem: With no volumes or mounts of any kind, containers stand up and run pretty nicely it seems. I tend to use bind mounts exclusively because I find named volumes a PITA for development and git deployments. When I bind-mount existing host directories, no problems either. The problems start when I want to specify new bind mount directories and start containers.

Could you add a little more detail? Here's an overview what we like to look for when reproducing issues: https://serversideup.net/ask-for-help/

[hughbris]

Ah crap, I made it too abstract. I was trying to avoid accusations of being self-promoting by linking to my image repo. Also, truth be told, I'm actually embarrassed revealing my low level docker chops.

Here's an overview what we like to look for when reproducing issues

I've shoehorned this into your issue template and it will get repetitive.

👉 Describe the problem

I'm porting a CMS image to use your FrankenPHP image as the new base. I cannot stand up a fresh instance of the CMS with bind mounted persistent directories on the host.

• The image contains ephemeral and (suggested) persistent directories. I typically bind mount the persistent directories. (Take a look at docker-compose files for tests 3 or 4 below for examples.)
• The CMS requires file ownership and permissions to be checked and set if incorrect at runtime/startup, including the persistent directories. Files under the web root must also be owned by the unprivileged user.
• When I start a new container with bind mounted targets on the host that do not exist, the directories are created with root ownership. Because the startup script which checks and sets permissions runs as the unprivileged user, permissions cannot be set and the CMS will not bootstrap. Only root can do that. (Test 1 below reproduces this. It's the main problem. The others illustrate variants that do work as expected.)
• Under other mount variations and with the old image (Test 3 below), the container serves the test page successfully:
  • When I start a container with bind mount targets from an existing successful instance, which do exist and are owned by the unprivileged user, the CMS stands up. (Test 4 demonstrates.)
  • When I start a container and omit the bind mounts (so it is an ephemeral, fresh CMS instance), the CMS stands up. (Test 2 shows that.)

📝 Steps to reproduce

Here are steps for four variations of containers you can recreate. The first recreates the problem. The others are variants for comparison:

General setup

You might need to set these variables for your environment or preferences: UID/GID, port, a common container name prefix, and possibly host mount targets. To be safe, make sure your host user has permissions to create directories under the parent of the host mounts you specify.

You can modify most of these settings by creating this file and placing it as .env in the test directory we will create in the next steps.

.env

# NAME_PREFIX=
# PUID=83
# PGID=83
# PORT=562X

Here is the setup process I followed:

$ mkdir -p ~/tmp/repro
$ cd ~/tmp/repro

Compose files

All tests bring up containers using docker compose. This is a threadbare base docker-compose.yaml I used for common options in all tests. Copy and save it into ~/tmp/repro:

docker-compose.yaml

services:

    grav:

        environment:
            LOG_LEVEL: 10

Smoke tests

1. The container should continue running.
2. On running containers, the curl command curl -I 127.0.0.1:<port> should show 200 OK status output.
3. Optionally you can look at docker logs.
4. On containers using bind mounts (Tests 1/3/4), a testX/user directory should be created with non-root user and group ownership.

Test 1

We will set up and run a container based on SSU's FrankenPHP variant with bind mounts to host directories that do not exist. Copy and create this docker-compose file, saving as test1.yaml:

test1.yaml

name: d562_test1
services:

    grav:
        build:
          context: https://github.com/hughbris/cadaver.git#ssu-franken
          args:
            php_ver: 8.4
            PUID: ${PUID:-1000}
            PGID: ${PGID:-1000}
        container_name: ${NAME_PREFIX:-d562}-test1

        ports:
            - "127.0.0.1:${PORT:-5621}:8080"

        volumes:
            # - ./test1/backup:/var/www/grav/backup # unnecessary for testing and development, uncomment if you like
            # - ./test1/logs:/var/www/grav/logs # unnecessary for testing and development, uncomment if you like
            - ./test1/user:/var/www/grav/user

I recommend starting this one with attached terminal output (no -d flag):

$ docker-compose -f docker-compose.yaml -f test1.yaml up

As the first test, this will initiate a build process which will take some time.

(Also I'm aware that there is quite a bit of setup in my Dockerfile that there is a probably superior SSU utility for. Replacement is still in progress.)

Test 2

We will set up and run a container based on SSU's FrankenPHP variant without any mounts to host directories. The container will be completely ephemeral. Copy and create this docker-compose file, saving as test2.yaml:

test2.yaml

name: d562_test2
services:

    grav:
        build:
          context: https://github.com/hughbris/cadaver.git#ssu-franken
          args:
            php_ver: 8.4
            PUID: ${PUID:-1000}
            PGID: ${PGID:-1000}
        container_name: ${NAME_PREFIX:-d562}-test2

        ports:
            - "127.0.0.1:${PORT:-5622}:8080"

Now fire it up:

$ docker-compose -f docker-compose.yaml -f test2.yaml up -d

Test 3

We will set up and run a container based on a current packaged image, which uses official php-fpm and with main process running nasty privileged. We bind mount to host directories that do not exist. Copy and create this docker-compose file, saving as test3.yaml:

test3.yaml

name: d562_test3
services:

    grav:
        image: ghcr.io/hughbris/cadaver:dev
        build: # alt build option (*)
          context: https://github.com/hughbris/cadaver.git#develop
          args:
            php_ver: 8.4
            PUID: ${PUID:-1000}
            PGID: ${PGID:-1000}
        container_name: ${NAME_PREFIX:-d562}-test3

        ports:
            - "127.0.0.1:${PORT:-5623}:2015"

        volumes:
            # - ./test3/backup:/var/www/grav/backup # unnecessary for testing and development, uncomment if you like
            # - ./test3/logs:/var/www/grav/logs # unnecessary for testing and development, uncomment if you like
            - ./test3/user:/var/www/grav/user

(*) If you need a uid/gid other than 1000, you'll need to remove the services.grav.image line, and a custom image will be built for you. This will take some time of course.

Now fire it up:

$ docker-compose -f docker-compose.yaml -f test3.yaml up -d

Test 4

We will set up and run a container based on SSU's FrankenPHP variant with bind mounts to host directories that do exist. In fact, which we created in the previous test. We'll do this and retain our naming convention by symlinking:

$ ln -s test3 test4

Note there is an extra step here! ☝️

Now copy and create this docker-compose file, saving as test4.yaml:

test4.yaml

name: d562_test4
services:

    grav:
        build:
          context: https://github.com/hughbris/cadaver.git#ssu-franken
          args:
            php_ver: 8.4
            PUID: ${PUID:-1000}
            PGID: ${PGID:-1000}
        container_name: ${NAME_PREFIX:-d562}-test4

        ports:
            - "127.0.0.1:${PORT:-5624}:8080"

        # don't forget to symlink!: `ln -s test3 test4`
        volumes:
            # - ./test4/backup:/var/www/grav/backup # unnecessary for testing and development, uncomment if you like
            # - ./test4/logs:/var/www/grav/logs # unnecessary for testing and development, uncomment if you like
            - ./test4/user:/var/www/grav/user

Now fire it up:

$ docker-compose -f docker-compose.yaml -f test4.yaml up -d

🙏 Expected behavior

All variations will produce containers that return HTTP 200 OK status on the port served on the host machine:

$ curl -I 127.0.0.1:<port>
HTTP/1.1 200 OK
…

🔥 Actual behavior

Test 1 FAILS:

• container exits with error status ✘

  $ docker container ls -a | grep test1
  a5f480801dd2   d562_test1-grav                          "docker-php-serversi…"   12 minutes ago   Exited (123) 12 minutes ago                                                             d562-test1

• creates an empty directory at bind mounts on the host, which cannot be modified by the host's ordinary user ✘

  $ ls -lR test1
  drwxr-xr-x root root 4.0 KB Fri Sep 26 16:26:02 2025  user
  
  test1/user:

• shows errors in its starting log ✘

  tail of log

  d562-test1  |                      Caddy serving Grav in Docker
  d562-test1  | 
  d562-test1  | 🛈 🛈 🛈 Init script starting 🛈 🛈 🛈
  d562-test1  | 🛈 🛈 🛈 Setting up into /var/www/grav from /tmp/fresh 🛈 🛈 🛈
  d562-test1  | 🗲 🗲 🗲 Fresh install, moving backup 🗲 🗲 🗲
  d562-test1  | 🗸 🗸 🗸 Moved backup 🗸 🗸 🗸
  d562-test1  | 🗲 🗲 🗲 Fresh install, moving logs 🗲 🗲 🗲
  d562-test1  | 🗸 🗸 🗸 Moved logs 🗸 🗸 🗸
  d562-test1  | 🗲 🗲 🗲 Fresh install, moving user directories 🗲 🗲 🗲
  d562-test1  | cp: can't create directory '/var/www/grav/user/accounts': Permission denied
  d562-test1  | cp: can't create directory '/var/www/grav/user/config': Permission denied
  d562-test1  | cp: can't create directory '/var/www/grav/user/data': Permission denied
  d562-test1  | cp: can't create directory '/var/www/grav/user/pages': Permission denied
  d562-test1  | cp: can't create directory '/var/www/grav/user/plugins': Permission denied
  d562-test1  | cp: can't create directory '/var/www/grav/user/themes': Permission denied
  d562-test1  | 🗶 🗶 🗶 Could not move all user directories 🗶 🗶 🗶
  d562-test1  | 🗲 🗲 🗲 Moving Grav core 🗲 🗲 🗲
  d562-test1  | 🛈 🛈 🛈 Using Grav's default robots.txt 🛈 🛈 🛈
  d562-test1  | 🗲 🗲 🗲 Cleaning up working files 🗲 🗲 🗲
  d562-test1  | 🗲 🗲 🗲 Setting permissions with chmod (+ chown, umask) 🗲 🗲 🗲
  d562-test1  | chown: ./user: Operation not permitted
  d562-test1 exited with code 123
  

Tests 2-4 PASS:

• Test 2 and Test 4 differ only in their mounts

• Test 3 differs in the image used

• These containers:

  • continue running ✔
  • serve expected HTTP content on their designated port ✔

  $ curl -I 127.0.0.1:<port>
  HTTP/1.1 200 OK
  …
  

  • do not show critical errors in their starting logs ✔
  tail of log

  $ docker logs d562-test<x>
  …
  Caddy serving Grav in Docker
  
  🛈 🛈 🛈 Init script starting 🛈 🛈 🛈
  🛈 🛈 🛈 Setting up into /var/www/grav from /tmp/fresh 🛈 🛈 🛈
  🗲 🗲 🗲 Fresh install, moving backup 🗲 🗲 🗲
  🗸 🗸 🗸 Moved backup 🗸 🗸 🗸
  🗲 🗲 🗲 Fresh install, moving logs 🗲 🗲 🗲
  🗸 🗸 🗸 Moved logs 🗸 🗸 🗸
  🗲 🗲 🗲 Fresh install, moving user directories 🗲 🗲 🗲
  🗸 🗸 🗸 Moved user directories 🗸 🗸 🗸
  🗲 🗲 🗲 Moving Grav core 🗲 🗲 🗲
  🛈 🛈 🛈 Using Grav's default robots.txt 🛈 🛈 🛈
  🗲 🗲 🗲 Cleaning up working files 🗲 🗲 🗲
  🗲 🗲 🗲 Setting permissions with chmod (+ chown, umask) 🗲 🗲 🗲
  🗸 🗸 🗸 Done setting permissions 🗸 🗸 🗸
  🗲 🗲 🗲 Setting file size limit (ulimit) to 8192 🗲 🗲 🗲
  🛈 🛈 🛈 This is the default file size limit, tweak it with $FILE_SIZE_LIMIT 🛈 🛈 🛈
  🗸 🗸 🗸 Init steps completed 🗸 🗸 🗸

  • allow any bind mounted content to be edited by the non-root host user ✔

  $ echo 'yo what up?' >> test3/user/pages/02.typography/default.md
  $ tail -n2 test3/user/pages/02.typography/default.md
  
  yo what up?

🌎 Environment

Docker on Linux.

📸 Additional context

I don't think so.

[hookenz]

I think I had the same problem but figured it out after some reading.

Docker volumes and mounts are initialised before the container is started and always by the user "root".
When you copy files in the Dockerfile the owner is always "root" by default so you have to set the owner.

COPY --chown=www-data:www-data . /var/www/html

Alternatively in your Dockerfile you switch to the "root" user, update the permissions and then set the user back to "www-data".

USER root
COPY ...
RUN chown -R www-data:www-data /var/www/html
USER www-data

Of course I may have completely misunderstood what you're talking about @hughbris

[hughbris]

Thanks for chipping in. I'm pretty sure I've been 'round the block with what you've suggested but I'd have to get my head back there to verify, and that can be difficult with Docker logic at the best of times. I'm actively traveling so I might need to sit on this for a bit before telling you why I don't think that flies. On top of that, my laptop hardware is flaking but I'm in Taiwan which must be about the best to place to sort that out.