gbeine/pass repository overview

⁠pass-docker - a minimalistic password vault based on GnuPG and pass

The purpose of this image is to provide a secure-enough solution for fetching passwords out of an encrypted storage.

⁠Start and initialization

Create a cointainer e.g. by using Docker or podman:

docker run --name pass-storage -v ./config:/config -d docker.io/gbeine/pass:latest

podman run --name pass-storage -v ./config:/config -d docker.io/gbeine/pass:latest

The container does not require network access and does not provide any ports.

Then create a GnuPG key by running:

podman exec -it pass-storage gpg --full-generate-key

And afterwards create the password store by running and replace your-key-id with the e-mail address used for the generated gpg key:

podman exec pass-storage pass init your-key-id 

⁠Usage

⁠Adding passwords

To add passwords to the store run:

podman exec -it pass-storage pass add path/key

⁠Enable password retrieval

To open the container (the gpg-agent session) for password retrieval run:

podman exec -it pass-storage pass ls

Use this after a reboot or a session timeout. As the gpg key password is requested, the -it is required.

⁠Fetch a passsord

To retrieve passwords from the store run:

podman exec pass-storage pass path/key

⁠Technical Foundation

The image is based on LinuxServer.io⁠'s Alpine Linux base image⁠. It uses gpg-agent to create a session which stays active for 48 hours.

⁠Parameters

Containers are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate <external>:<internal> respectively. For example, -p 8080:80 would expose port 80 from inside the container to be accessible from the host's IP on port 8080 outside the container.

⁠User / Group Identifiers

When using volumes (-v flags), permissions issues can arise between the host OS and the container, we avoid this issue by allowing you to specify the user PUID and group PGID.

Ensure any volume directories on the host are owned by the same user you specify and any permissions issues will vanish like magic.

In this instance PUID=1000 and PGID=1000, to find yours use id your_user as below:

id your_user

Example output:

uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

⁠Links

• project site⁠
• pass⁠
• pass man page⁠
• GnuPG⁠
• gpg manual⁠
• gpg-agent manual⁠

⁠Versions

• 13.08.25: - Initial release based on Alpine 3.22
• 05.05.25: - Initial release based on Alpine 3.21