### Install su-exec on Alpine Linux

Source: https://context7.com/ncopa/su-exec/llms.txt

Install su-exec using apk on Alpine Linux. Verify the installation and use it in an entrypoint script to execute commands as a non-root user.

```dockerfile
FROM alpine:3.19

# Install su-exec (< 20 KB installed)
RUN apk add --no-cache su-exec

# Verify installation
RUN su-exec --help 2>&1 || true
# Usage: su-exec user-spec command [args]

# Create application user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

COPY --chown=root:root entrypoint.sh /entrypoint.sh
RUN chmod 755 /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]
```

```sh
# entrypoint.sh
#!/bin/sh
set -e
exec su-exec appuser:appgroup "$@"
```

--------------------------------

### su-exec error handling examples

Source: https://context7.com/ncopa/su-exec/llms.txt

su-exec exits with code 1 and prints errors to stderr for common failures like unknown users, permission issues, or missing commands. Check the exit code in scripts.

```sh
# Unknown user — exits 1
su-exec nonexistent /bin/sh
# su-exec: getpwnam(nonexistent): No such file or directory
```

```sh
# Not running as root — setuid fails, exits 1
su-exec nobody /bin/sh          # run as unprivileged user
# su-exec: setuid(65534): Operation not permitted
```

```sh
# Command not found — exits 1
su-exec nobody /nonexistent-binary
# su-exec: /nonexistent-binary: No such file or directory
```

```sh
# Insufficient arguments — prints usage, exits 1
su-exec nobody
# Usage: su-exec user-spec command [args]
```

```sh
# Check exit code in a script
if ! su-exec appuser /usr/local/bin/migrate --check; then
  echo "Migration pre-check failed" >&2
  exit 1
fi
exec su-exec appuser /usr/local/bin/server
```

--------------------------------

### Build su-exec with Make

Source: https://context7.com/ncopa/su-exec/llms.txt

Compile su-exec using make. Supports dynamic, static builds, and overriding compiler flags. Verify binary size and clean artifacts.

```sh
# Dynamic build (default)
make
```

```sh
# Static build — ideal for scratch or musl-based containers
make su-exec-static
```

```sh
# Override compiler flags
make CFLAGS="-Wall -O2" LDFLAGS=""
```

```sh
# Verify the binary is small (~10 KB)
ls -lh su-exec
```

```sh
# Clean build artifacts
make clean
```

--------------------------------

### Docker Entrypoint Pattern with su-exec

Source: https://context7.com/ncopa/su-exec/llms.txt

A common container pattern where an entrypoint script initializes as root, then uses su-exec to hand off to the application as a non-root user, making the application PID 1.

```dockerfile
# Dockerfile
FROM alpine:3.19

RUN apk add --no-cache su-exec

COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

ENTRYPOINT ["docker-entrypoint.sh"]
```

```sh
#!/bin/sh
# docker-entrypoint.sh

set -e

# Fix ownership of a mounted volume at runtime
chown -R postgres:postgres /var/lib/postgresql/data

# Drop from root to postgres and exec — becomes PID 1
exec su-exec postgres "$@"
```

```sh
# Run the container; the application process is PID 1, not a shell
docker run --rm myimage postgres -D /var/lib/postgresql/data
```

```sh
# Verify inside the container
docker run --rm myimage su-exec postgres ps aux
```

--------------------------------

### Basic Usage: Switch User and Execute Command

Source: https://context7.com/ncopa/su-exec/llms.txt

Run any command as a different user. 'user-spec' can be a username, UID, 'user:group', or 'uid:gid'. su-exec must be run as root.

```sh
# Run a shell as 'nobody'
su-exec nobody /bin/sh
```

```sh
# Run httpd as 'apache' with group 'www-data'
su-exec apache:www-data /usr/sbin/httpd -f /opt/www/httpd.conf
```

```sh
# Use numeric UID/GID instead of names
su-exec 1000:1000 /usr/local/bin/myapp --config /etc/myapp.conf
```

```sh
# Use only a numeric UID (group resolves from /etc/passwd)
su-exec 33 /usr/bin/php-fpm --nodaemonize
```

--------------------------------

### TTY and Signal Handling Comparison: su vs su-exec

Source: https://context7.com/ncopa/su-exec/llms.txt

Demonstrates why su-exec is preferred in containers for direct signal delivery to the target process, unlike 'su' which uses a shell wrapper.

```sh
# BAD: using 'su' — ps aux shows a shell as PID 1 wrapping the real command
docker run -it --rm alpine:edge su postgres -c 'ps aux'
```

```sh
# GOOD: using su-exec — the real command IS PID 1
docker run -it --rm -v $PWD/su-exec:/sbin/su-exec:ro alpine:edge \
  su-exec postgres ps aux
```

```sh
# Signal test: SIGTERM reaches the app immediately
docker stop <container>  # sends SIGTERM → goes directly to the app, not a shell
```

--------------------------------

### Verify user and group with su-exec

Source: https://context7.com/ncopa/su-exec/llms.txt

Use su-exec to run the 'id' command to verify the effective user and group, including supplementary groups.

```sh
su-exec deploy id
# uid=1001(deploy) gid=1001(deploy) groups=1001(deploy),999(docker),4(adm)
```

```sh
su-exec deploy:docker id
# uid=1001(deploy) gid=999(docker) groups=999(docker)
```

--------------------------------

### su vs su-exec Process Handling

Source: https://github.com/ncopa/su-exec/blob/master/README.md

Demonstrates the difference in process handling between `su` and `su-exec`. `su-exec` executes the command directly, while `su` runs it as a child of a shell.

```shell
$ docker run -it --rm alpine:edge su postgres -c 'ps aux'
PID   USER     TIME   COMMAND
    1 postgres   0:00 ash -c ps aux
   12 postgres   0:00 ps aux
```

```shell
$ docker run -it --rm -v $PWD/su-exec:/sbin/su-exec:ro alpine:edge su-exec postgres ps aux
PID   USER     TIME   COMMAND
    1 postgres   0:00 ps aux
```

--------------------------------

### su-exec with User and Group Specification

Source: https://github.com/ncopa/su-exec/blob/master/README.md

Execute a command as a specified user and group. Both user and group can be specified by name or numeric ID.

```shell
$ su-exec apache:1000 /usr/sbin/httpd -f /opt/www/httpd.conf
```

--------------------------------

### Basic su-exec Usage

Source: https://github.com/ncopa/su-exec/blob/master/README.md

Execute a command as a specified user. The user-spec can be a username or a numeric UID.

```shell
su-exec user-spec command [ arguments... ]
```

--------------------------------

### Supplementary Group Handling with su-exec

Source: https://context7.com/ncopa/su-exec/llms.txt

When only a username is provided, su-exec uses getgrouplist to set all supplementary groups. An explicit group limits it to that single group.

```sh
# User 'deploy' belongs to groups: deploy(1001), docker(999), adm(4)
# This command sets all three supplementary groups automatically:
su-exec deploy /usr/local/bin/deploy-app
```

--------------------------------

### Override user and group with su-exec

Source: https://context7.com/ncopa/su-exec/llms.txt

Use su-exec to run a command as a specific user, optionally overriding the primary group. Supplementary groups are dropped when an explicit group is provided.

```sh
su-exec deploy:docker /usr/local/bin/docker-health-check
```

```sh
su-exec deploy:999 /usr/local/bin/docker-health-check
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.