PSS®X package for Valkey ¶

What is Valkey ?¶

The respective trademarks mentioned in the offering are owned by the respective companies, and use of them does not imply any affiliation or endorsement

Featured tags¶

• 8.0.1-bookworm-slim-25.4.0-amd64
  docker pull registry.gitlab.com/pss-x/support/containers/valkey:8.0.1-bookworm-slim-amd64

About this image¶

This is a non-root container image, which adds an extra layer of security and is generally recommended for production environments. However, because they run as a non-root user, privileged tasks are typically off-limits.

How to use this image¶

You can get started with Valkey

docker run --name pssx-valkey -e "VALKEY_VALKEY_ALLOW_EMPTY_PASSWORD=yes" -p 6379:6379 -d registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tags>

Warning: These quick setups are only intended for development environments. You are encouraged to change the insecure default credentials and check out the available configuration options in the Configuration section for a more secure deployment.

Configuration¶

Requirements¶

You can build your development environment with non-production hardware, such as a laptop, desktop, or small VM or instance, and with these hardware requirements:

• This image requires Docker Engine 1.8+ in any of their supported platforms
• You can install on one node but many features require at least two nodes.
• Amount of 4GB RAM is needed for each node.
• Amount of 10GB storage space is needed for each node.

Environment variables¶

Customizable environment variables¶

Read-only environment variables¶

Using a Docker Compose file¶

Using Docker container networking, a Valkey server running inside a container can easily be accessed by your application containers.

Containers attached to the same network can communicate with each other using the container name as the hostname.

services:
  valkey:
    container_name: pssx-valkey
    image: registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag>
    ports:
      - 6379:6379
    environment:
      - VALKEY_ALLOW_EMPTY_PASSWORD=yes
    networks:
      - pssx-network

networks:
  pssx-network:
    name: app-pssx-network
    driver: bridge

Setting up a standalone instance¶

By default, this image is set up to launch Valkey in standalone mode on port 6379. Should you need to change this behavior, setting the VALKEY_PORT_NUMBER environment variable will modify the port number.

services:
  valkey:
  ...
    environment:
      - VALKEY_PORT_NUMBER=7000
    ...
    ports:
      - '7000:7000'
  ...

Persisting your database¶

Valkey provides a different range of persistence options. This contanier uses AOF persistence by default but it is easy to overwrite that configuration in a docker-compose.yaml file with this entry command: /opt/siemens/scripts/valkey/run.sh --appendonly no. Alternatively, you may use the VALKEY_AOF_ENABLED env variable as explained in Disabling AOF persistence.

If you remove the container all your data will be lost, and the next time you run the image the database will be reinitialized. To avoid this loss of data, you should mount a volume that will persist even after the container is removed.

For persistence you should mount a directory at the /siemens/valkey/data path. If the mounted directory is empty, it will be initialized on the first run.

docker run \
    -e VALKEY_ALLOW_EMPTY_PASSWORD=yes \
    -v /path/to/valkey-persistence:/siemens/valkey/data \
    registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag>

You can also do this by modifying the docker-compose.yml file present in this repository:

services:
  valkey:
    ...
    volumes:
      - valkey_data:/siemens/valkey/data
    ...

volumes:
  valkey_data:
    name: pssx_valkeydata
    driver: local
    ...

NOTE: As this is a non-root container, the mounted files and directories must have the proper permissions for the UID 1001.

Passing extra command-line flags to valkey-server startup¶

Passing extra command-line flags to the valkey service command is possible by adding them as arguments to run.sh script:

docker run --name valkey -e VALKEY_ALLOW_EMPTY_PASSWORD=yes registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag> /opt/siemens/scripts/valkey/run.sh --maxmemory 100mb

Alternatively, modify the docker-compose.yml file present in this repository:

services:
  valkey:
  ...
    environment:
      - VALKEY_ALLOW_EMPTY_PASSWORD=yes
    command: /opt/siemens/scripts/valkey/run.sh --maxmemory 100mb
  ...

Refer to the Valkey documentation for the complete list of arguments.

Configuration file¶

The image looks for configurations in /opt/siemens/valkey/mount/valkey.conf. You can overwrite the valkey.conf file using your own custom configuration file.

docker run --name valkey \
    -e VALKEY_ALLOW_EMPTY_PASSWORD=yes \
    -v /path/to/your_valkey.conf:/opt/siemens/valkey/mount/valkey.conf \
    registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag>

Alternatively, modify the docker-compose.yml file present in this repository:

services:
  valkey:
  ...
    volumes:
      - /path/to/overrides.conf:/opt/siemens/valkey/mount/valkey.conf
  ...

Disabling Valkey commands¶

For security reasons, you may want to disable some commands. You can specify them by using the following environment variable on the first run:

• VALKEY_DISABLE_COMMANDS: Comma-separated list of Valkey commands to disable. Defaults to empty.

docker run --name valkey -e VALKEY_DISABLE_COMMANDS=FLUSHDB,FLUSHALL,CONFIG registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag>

Alternatively, modify the docker-compose.yml file present in this repository:

services:
  valkey:
  ...
    environment:
      - VALKEY_DISABLE_COMMANDS=FLUSHDB,FLUSHALL,CONFIG
  ...

As specified in the docker-compose, FLUSHDB and FLUSHALL commands are disabled. Comment out or remove the environment variable if you don't want to disable any commands:

services:
  valkey:
  ...
    environment:
      # - VALKEY_DISABLE_COMMANDS=FLUSHDB,FLUSHALL
  ...

Disabling AOF persistence¶

Valkey offers different options when it comes to persistence. By default, this image is set up to use the AOF (Append Only File) approach. Should you need to change this behaviour, setting the VALKEY_AOF_ENABLED=no env variable will disable this feature.

docker run --name valkey -e VALKEY_AOF_ENABLED=no registry.gitlab.com/pss-x/support/containers/valkey:<use-featured-tag>

Alternatively, modify the docker-compose.yml file present in this repository:

services:
  valkey:
  ...
    environment:
      - VALKEY_AOF_ENABLED=no
  ...

Handling sensitive information¶

In Docker, environment variables with the _FILE suffix are a convention used to specify that the value of the environment variable should be read from a file.

• Environment Variable with _FILE Suffix: When an environment variable ends with _FILE, it indicates that the actual value of the variable should be read from the file specified by the path.
• Usage in Docker: This approach is commonly used in Docker to securely pass sensitive information to containers without hardcoding the values in the docker-compose.yml file or Dockerfile.

services:
  valkey:
    ...
    environment:
      - VALKEY_ALLOW_EMPTY_PASSWORD=no
      - VALKEY_PASSWORD_FILE=/run/secrets/VALKEY_PASSWORD
    secrets:
      - VALKEY_PASSWORD
    ...

secrets:
  VALKEY_PASSWORD:
    file: ./etc/secrets/valkey.pwd
    ...

Health checks¶

The healthcheck section in a Docker Compose file allows you to define a command that Docker will run to check the health of a service. This helps ensure that your services are running correctly and can automatically handle failures.

services:
  rabbitmq:
    ports:
      - 6379:6379
    ...
    healthcheck:
      test: ["CMD", "valkey-cli","ping"]
    ...

The valkey-cli ping command requires tcp port since tls is not activated. Default tcp port is 6379 for Valkey .

Securing Valkey traffic¶

Starting with version 6, Valkey(R) adds the support for SSL/TLS connections. Should you desire to enable this optional feature, you may use the following environment variables to configure the application:

• VALKEY_TLS_ENABLED: Whether to enable TLS for traffic or not.
  Defaults to no.
• VALKEY_TLS_PORT_NUMBER: Port used for TLS secure traffic.
  Defaults to 6379.
• VALKEY_TLS_CERT_FILE: File containing the certificate file for the TLS traffic.
  No defaults.
• VALKEY_TLS_KEY_FILE: File containing the key for certificate.
  No defaults.
• VALKEY_TLS_CA_FILE: File containing the CA of the certificate (takes precedence over VALKEY_TLS_CA_DIR).
  No defaults.
• VALKEY_TLS_CA_DIR: Directory containing the CA certificates.
  No defaults.
• VALKEY_TLS_DH_PARAMS_FILE: File containing DH params (in order to support DH based ciphers).
  No defaults.
• VALKEY_TLS_AUTH_CLIENTS: Whether to require clients to authenticate or not.
  Defaults to yes.

services:
  rabbitmq:
    ...
    ports:
      - 6379:6379
      - 7000:7000
    environment:
      - VALKEY_ALLOW_EMPTY_PASSWORD=no
      - VALKEY_PASSWORD_FILE=/run/secrets/VALKEY_PASSWORD
      - VALKEY_TLS_ENABLED=yes
      - VALKEY_TLS_PORT_NUMBER=7000
      - VALKEY_TLS_CA_FILE=/opt/siemens/valkey/certs/myOrganizationRootCA.pem
      - VALKEY_TLS_CERT_FILE=/opt/siemens/valkey/certs/myOrganizationCert.pem
      - VALKEY_TLS_KEY_FILE=/opt/siemens/valkey/certs/myOrganizationCertKey.pem
      - VALKEY_TLS_AUTH_CLIENTS=yes
      - VALKEY_DISABLE_COMMANDS=FLUSHDB,FLUSHALL,CONFIG
    secrets:
      - VALKEY_PASSWORD
    volumes:
      - ./etc/certs:/opt/siemens/valkey/certs
    ...
    healthcheck:
      test: ["CMD", "valkey-cli","ping"]
    ...

secrets:
  VALKEY_PASSWORD:
    external: true

Note that mkcert and the certificate/key pairs it generates are self-signed and only suitable for development and test environments. The vast majority of production environments should use certificates and keys issued by a widely trusted commercial CA.

services:
  rabbitmq:
    ...
    ports:
      - 6379:6379
      - 7000:7000
    environment:
      - VALKEY_ALLOW_EMPTY_PASSWORD=no
      - VALKEY_PASSWORD_FILE=/run/secrets/VALKEY_PASSWORD
      - VALKEY_TLS_ENABLED=yes
      - VALKEY_TLS_PORT_NUMBER=7000
      - VALKEY_TLS_CA_FILE=/opt/siemens/valkey/certs/rootCA.pem
      - VALKEY_TLS_CERT_FILE=/opt/siemens/valkey/certs/cert.pem
      - VALKEY_TLS_KEY_FILE=/opt/siemens/valkey/certs/key.pem
      - VALKEY_TLS_AUTH_CLIENTS=no
      - VALKEY_DISABLE_COMMANDS=FLUSHDB,FLUSHALL,CONFIG
    secrets:
      - VALKEY_PASSWORD
    volumes:
      - ./etc/certs:/opt/siemens/valkey/certs
    ...
    healthcheck:
      test: ["CMD", "valkey-cli","ping"]
    ...

secrets:
  VALKEY_PASSWORD:
    file: ./etc/secrets/valkey.pwd

License¶

Valkey is an open source (BSD) high-performance key/value datastore that supports a variety of workloads such as caching, message queues, and can act as a primary database. Valkey can run as either a standalone daemon or in a cluster, with options for replication and high availability.

Valkey natively supports a rich collection of datatypes, including strings, numbers, hashes, lists, sets, sorted sets, bitmaps, hyperloglogs and more. You can operate on data structures in-place with an expressive collection of commands. Valkey also supports native extensibility with built-in scripting support for Lua and supports module plugins to create new commands, data types, and more.