Configuring Registry Credentials and Secrets Vault in Docker

Before deploying custom containerized applications with Docker Stacks, you can configure your private container registries and securely store sensitive application secrets.

RunCloud manages these settings at the workspace level. This means you only need to enter your registry credentials and sensitive keys once. They are securely stored and made available across all containerized servers in your workspace.

Adding Registry Credentials

If you plan to deploy custom or proprietary images hosted in private container registries, RunCloud must authenticate with your registry provider before pulling the container image.

RunCloud supports the following registry providers:

• Docker Hub
• GitHub Container Registry (GHCR)
• Google Container Registry (GCR) / Google Artifact Registry
• AWS Elastic Container Registry (ECR)
• Azure Container Registry (ACR)
• Custom Registries (Self-hosted or third-party OCI-compliant registries)

How Automatic Credential Matching Works

When you type an image name in the Docker Stacks deployment wizard (for example, ghcr.io/your-organization/your-app:latest), RunCloud automatically inspects the image URL.

It then matches the domain name of the registry against your saved credentials in your workspace settings.

Step-by-Step Instructions: Adding a Registry Credential

Follow these steps to store your private registry authentication details:

1. Log in to your RunCloud control panel.
2. Navigate to Settings > Registry Credentials from the workspace settings navigation menu (or click Settings in the global left sidebar).
3. Click Add Credential to open the credential configuration modal.

4. Select your registry provider from the “Provider” dropdown menu. For example, you can select “GitHub Container Registry” for images hosted under ghcr.io or select “Custom Registry” if you run a self-hosted registry or want to use another provider.
5. If you selected “Custom Registry”, enter the full URL of your registry server in the “Registry URL” field.

6. Enter your account username in the “Username” field.
7. Enter your personal access token, API key, or account password in the “Password / Token” field.

Security Best Practice: When connecting to Docker Hub or GitHub, always generate a personal access token with read-only permissions (read:packages) rather than using your primary account password.

Choose your credential server scope:

• Leave it empty if you want all servers in your workspace to access this registry.
• If you wish to restrict this credential to specific machines, deselect the checkbox and choose the designated servers from the list.

8. Click Save to complete the setup.

RunCloud will verify your authentication details and securely store the credentials in your workspace.

Storing Sensitive Data in the Secrets Vault

Containerized applications often require sensitive configuration values, such as payment gateway keys, database passwords, OAuth client secrets, and SSL/TLS certificates.

Why You Shouldn’t Use Plain-Text Environment Variables

In traditional server setups, developers often paste API keys and passwords directly into plain-text environment variables. Although this is convenient, this practice introduces severe security risks:

• Plain-text environment variables can be inspected by any process running on the host server.
• Environment variables are frequently printed into application error traces and diagnostic log files during crashes.
• Anyone who has view access to a deployment dashboard can read the credentials in plain text.

The RunCloud Secrets Vault Benefits

To eliminate these vulnerabilities, RunCloud includes a centralized, encrypted Secrets Vault at the workspace level. The Secrets Vault provides three layers of enterprise-grade security:

1. Write-Only Storage: Once you save a secret in the vault, its raw value is immediately encrypted and masked. It cannot be retrieved or viewed in plain text by team members through the dashboard interface.
2. Encrypted at Rest: Secrets are protected using strong cryptographic standards before being stored in the database.
3. Delivered as Secure File Mounts: Instead of injecting credentials into vulnerable environment variables, RunCloud delivers your secrets as read-only files mounted at specific paths inside your container (for example, /run/secrets/api_key). The container reads the secret directly from the mounted file, keeping the sensitive value out of the server environment and log streams.

Step-by-Step Instructions: Adding a Secret to the Vault

Follow these steps to store a sensitive credential in your Secrets Vault:

1. Navigate to Settings > Secrets in your RunCloud dashboard.
2. Click New Secret to open the secret creation form.

3. Enter a descriptive, recognizable identifier in the “Name” field (for example STRIPE_PRIVATE_KEY or DATABASE_ROOT_PASSWORD).
4. Select the type of credential from the dropdown and paste your sensitive token, certificate text, or password into the “Value” field.

5. Click Create to encrypt and store the value.

The secret will now appear in your list of available secrets, with its contents masked for security.

How to Assign Secrets to Containers During Deployment

When you configure a container in Docker Stacks, you can attach any saved secret to your container:

1. In the container configuration form, scroll to the “Secrets” section.
2. Click Assign Secret.
3. Select your desired secret from the dropdown list.
4. Specify the internal container mount path where the secret file should appear (for example, /etc/secrets/stripe_key.txt).
5. Save your container settings.

When the container starts, RunCloud creates a read-only, in-memory file at that exact path containing your secret, ensuring maximum application security.