Container Deployment

When deploying DBCode in containers, dev environments, or other automated setups, you can use environment variables to handle licensing without manual user interaction. This is designed for team subscriptions where an administrator pre-configures environments for team members.

Overview

Two environment variables control DBCode behavior in container environments:

Environment Variable	Purpose
DBCODE_ACTIVATION_TOKEN	Automatically activates a license on startup
DBCODE_REQUIRE_LICENSE	Blocks all DBCode functionality until a valid license is present

Both are optional and can be used independently or together.

Activation Tokens

An activation token lets DBCode automatically obtain a license when it starts up. The token is tied to a specific team member’s seat and is generated by a team owner or admin.

How It Works

1. A team admin generates an activation token for a seat member
2. The token is set as the DBCODE_ACTIVATION_TOKEN environment variable in the container
3. On startup, DBCode exchanges the token for a license (7-day expiry)
4. When the license nears expiry, DBCode automatically re-activates using the same token
5. If the token is revoked, the license is cleared on the next renewal attempt

Requirements

• A team subscription with 2 or more seats
• The person generating the token must be the account owner or an admin
• The container must have outbound network access to https://dbcode.io

Generating a Token

1. Open DBCode in Visual Studio Code

Launch Visual Studio Code and click the DBCode icon from the Activity Bar on the left.

2. Navigate to the Account Tab

In the DBCode sidebar, click on the Account tab and expand your license details.

3. Open the Seats Section

Expand the Seats section to see your team members.

4. Generate Token

Right-click on the team member you want to generate a token for and select Generate Activation Token. The token will be copied to your clipboard.

Caution

Each time you generate a new token for a seat, the previous token for that seat is automatically revoked. Only one active token exists per seat at any time.

Setting the Environment Variable

Set the token in your container configuration. The exact method depends on your container platform:

Docker:

docker run -e DBCODE_ACTIVATION_TOKEN=eyJhbGciOi... your-image

Docker Compose:

services:
  dev-environment:
    image: your-image
    environment:
      - DBCODE_ACTIVATION_TOKEN=eyJhbGciOi...

Kubernetes:

env:
  - name: DBCODE_ACTIVATION_TOKEN
    valueFrom:
      secretKeyRef:
        name: dbcode-secrets
        key: activation-token

The token is a JWT string and should be treated as a secret. Store it in your platform’s secret management system rather than in plain text configuration files.

Revoking a Token

Right-click on the team member in the Seats section and select Revoke Activation Token. The token is invalidated immediately on the server. The next time the extension tries to refresh the license (on any API call or permission sync), it detects the revocation and clears the license.

Token Lifecycle

• Set once: The token does not expire. Set it in your container config and it works until revoked.
• Renewal: When the 7-day license nears expiry, DBCode re-activates using the token automatically. No manual renewal needed.
• Revocation: Generating a new token or explicitly revoking one invalidates the previous token. The next time the extension attempts to refresh the license, it detects the revocation, clears the license, and blocks access.
• Container restarts: The license is cached locally. On restart, DBCode uses the cached license and re-activates if it has expired.

Team Roles

When a license is activated via token, team roles are automatically applied. If the seat member has a role assigned (e.g., restricted, no-export), those restrictions are enforced in the container environment. Role changes made by the admin take effect within 12 hours.

Require License Mode

Setting DBCODE_REQUIRE_LICENSE=true prevents DBCode from functioning without a valid license. When set and no license is available, all functionality is blocked, including connecting to databases, running queries, and browsing schemas.

This is useful for enforcing company policy in managed environments where you want to ensure team members only use DBCode with a properly licensed and configured account.

Setting the Environment Variable

DBCODE_REQUIRE_LICENSE=true

Combining with Activation Tokens

The typical setup uses both variables together:

DBCODE_ACTIVATION_TOKEN=eyJhbGciOi...
DBCODE_REQUIRE_LICENSE=true

This ensures the license is automatically activated and that DBCode cannot be used if the activation fails (e.g., network issues, revoked token).

Behavior When Blocked

When DBCODE_REQUIRE_LICENSE is set and no valid license is found:

• An error message is displayed: “DBCode requires a valid license to operate in this environment”
• All database connections are blocked
• All features (including core features) are unavailable
• The extension sidebar remains visible but non-functional

If a license is obtained later (via activation token, sign-in, or offline license), the block is lifted and full functionality is restored.

Comparison with Other Activation Methods

Method	Best For	Network Required	Machine Bound
Activation Token	Containers, automated environments	Yes (on startup + on expiry)	No (new license per machine)
Sign In (GitHub/Microsoft)	Interactive development	Yes (on sign-in)	No
Offline License	Air-gapped machines	Only during activation	Yes

For air-gapped containers with no network access, activation tokens will not work. Use offline license activation instead, though note that offline licenses are machine-bound and will not persist across ephemeral containers.

Troubleshooting

”Activation token exchange failed”

• Verify the container has outbound HTTPS access to dbcode.io
• Check that the token was copied correctly (it should start with eyJ)
• Verify the token has not been revoked (ask your team admin to generate a new one)

“Activation token has been revoked”

A new token was generated for the same seat, or the token was explicitly revoked by an admin. Get a new token from your team admin and update the environment variable.

”DBCode requires a valid license”

This appears when DBCODE_REQUIRE_LICENSE=true is set and no license could be obtained. Check:

• Is DBCODE_ACTIVATION_TOKEN also set?
• Can the container reach dbcode.io?
• Is the team subscription active?

License Not Renewing

If the license stops working:

• Verify the container can still reach dbcode.io
• Check that the activation token has not been revoked (ask your team admin)
• Restart VS Code to trigger an immediate re-activation attempt

Team Roles Not Applied

If feature restrictions from team roles are not being enforced:

• Roles require network access to sync
• Restart VS Code to force an immediate permission sync
• Verify the seat has a role assigned in the team seats panel

Need Help?

If you encounter issues with container deployment, contact help@dbcode.io for assistance.