Deploy the solution on premises

Deploy Self-Hosted Deployment on premises using the vpctl tool

Read time 5 minutes

Last updated 3 days ago

Before deployment, check the prerequisites. The deployment on premises uses the vpctl tool to manage the entire release lifecycle. If all prerequisites are met, the deployment takes 30 to 60 minutes. This time doesn't include the subsequent administration tasks, such as setting up an identity provider for single sign-on (SSO).

Note

For an end-to-end overview of how vpctl orchestrates the deployment (data flow, components, and trust boundaries), refer to vpctl architecture. This is useful for security teams reviewing the deployment.

Follow these steps to deploy Self-Hosted Deployment to your Kubernetes cluster.

1. Configure the registry credentials

Before you can pull releases, configure your ORAS registry credentials. This is a one-time setup. Run the interactive configuration:


vpctl configure

For non-interactive setup and credential verification, see Configure registry credentials.

2. Initialize the manifest file

The manifest file

manifest.yaml

contains your deployment configuration. The vpctl tool automatically discovers

manifest.yaml

in the current directory or in the parent directories. If you do not have a manifest file, create one:


vpctl manifest init

The interactive prompts ask for the platform, the release version, the source and target registries, the application domain, the Kubernetes namespace, the autoscaling settings, the monitoring options, the sizing profile, the Traefik service type, and the ArgoCD settings (if applicable).

Validate the manifest

To validate your manifest against the built-in schema before continuing, run this command:


vpctl manifest validate

This command checks the required fields, the allowed values, and the cross-field rules (for example,

maxReplicas >= minReplicas

Configure the manifest file

The manifest file controls the entire deployment. Here is a minimal skeleton:


platform: onpremreleaseVersion: 0.13.0artifactSync:  sourceRepository: uccmpprivatecloud.azurecr.ioconfiguration:  networking:    appDomain: example.com    ingress:      traefik:        type: LoadBalancer  kubernetes:    namespace: asset-solutions    docker:      repository: <your-registry-url>      namespace: <your-registry-namespace>    imagePullSecret: regcred  infrastructure:    sizing: medium

For the full schema, all configurable sections (networking, kubernetes, transformations, monitoring, authentication, infrastructure), and the

deployment.helmChartMode

and

deployment.argocd

options, refer to vpctl manifest reference.

3. Pull the release

Download the release package from the registry. The system reads the version from the manifest automatically:


vpctl release pull --clean-output

The system downloads the release archive and extracts it to

./extracted-release

. For all flags (including

--version

to override the manifest version), refer to vpctl release.

4. Sync the artifacts

Before deploying, sync the Docker images and the ORAS artifacts from the Unity source registry to your private registry. If you opted in to the

remote

Helm chart mode preview, also sync the published OCI Helm charts.

Note

If you pull container images directly from the Unity source registry rather than mirroring them to your own private registry, you can skip this step. Mirroring is recommended for air-gapped environments and for full control over image distribution.

4.1 Authenticate to both registries

You must authenticate to the source and target registries before syncing:


docker login uccmpprivatecloud.azurecr.iodocker login <your-registry-url>

4.2 Run the preflight check

Verify your credentials before running a full sync:


vpctl artifact sync preflight

This command syncs one Docker image, one ORAS artifact, and (if

helmChartMode

is set to

remote

) one Helm chart as a test. If the test fails, it prints troubleshooting hints.

4.3 Sync the Docker images

Preview the sync commands first, then run the sync:


vpctl artifact sync images --dry-runvpctl artifact sync images

4.4 Sync the ORAS artifacts

ORAS artifacts include OCI artifacts used by Helm charts. The sync reads authentication from the Docker credential store (

~/.docker/config.json

) automatically.


vpctl artifact sync oras --dry-runvpctl artifact sync oras

4.5 Sync the OCI Helm charts (preview, remote chart mode only)

If your manifest includes the setting

deployment.helmChartMode: remote

, mirror the OCI Helm charts that are published to the Unity registry. If you use the default

local

mode, skip this step, because charts are bundled in the release package.


vpctl artifact sync charts --dry-runvpctl artifact sync charts

For all flags (including

--skip-existing

--cleanup

--name

--concurrency

), refer to vpctl artifact.

5. Generate and deploy the secrets

Generate the secrets

To generate secrets:

Create a secrets import file based on the provided example:
```
secrets.import.example.yaml
```
.

This file contains secret values organized by secret name. Enter values in plain text; encoding is handled automatically. The example file enumerates every required secret (UVCS certificate, Elasticsearch, Mini-USF, Novu, MongoDB, PostgreSQL, RabbitMQ, Garage S3 credentials, Garage RPC secret, UVCS license, Valkey).

Generate the Kubernetes secret manifests:
```
vpctl secret generate --import secrets.import.yaml --use-defaults
```
By default, automatically-generated passwords are alphanumeric only. This limitation is to avoid breaking connection strings.
Note
With the
--use-defaults
option, the process sets any required field that has neither a default value nor an automatic-generation rule to
TBD
and logs a warning. Before deployment, replace all
TBD
values.
Optionally, persist the generated values for reuse on later runs:
```
vpctl secret generate --import secrets.import.yaml --use-defaults --persist
```
This command writes the generated values back to
```
secrets.import.yaml
```
. Subsequent runs reuse the persisted values, which keeps your deployments consistent across upgrades.

Note

The custody of secrets is your responsibility. The vpctl tool bootstraps the initial values into Kubernetes secrets, but Unity doesn't store, rotate, or back up your secrets. These files all contain sensitive values:

secrets.import.yaml

, the persisted file written by

--persist

, and the generated

secrets.yaml

. Don't commit these files to Git, but add them to your

.gitignore

file, store them encrypted at rest, and grant access to only the people and systems that need them.For production environments, we recommend keeping the source of truth for these values in a secret manager that you already operate (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or CyberArk). Feed the values into the

secrets.import.yaml

file from your secret manager at install or upgrade time. This pattern keeps rotation, audit, and access control under your existing security policies.

Deploy the secrets

Preview the deployment, then deploy the secrets to your cluster:


vpctl secret deploy --dry-runvpctl secret deploy

For all flags, refer to vpctl secret.

6. Generate and deploy the charts

Choose your deployment method: Helm or ArgoCD.

Option A: Helm deployment

Generate the Helm charts:


vpctl release generate --clean-output

Preview the deployment first:


vpctl release deploy --dry-run

For a first-time deployment, deploy the release in waves, starting with the lowest wave, for example,

-3

. Validate each wave before deploying the next to ensure all dependencies are satisfied.


vpctl release deploy --wave -3vpctl release deploy --wave -2vpctl release deploy --wave -1vpctl release deploy --wave 0

To deploy all charts at once:


vpctl release deploy

Verify the deployment

To check the status of the deployments:


kubectl get pods --all-namespaces --watch

Ensure that all pods eventually move to the Running state. If a pod isn't running, describe it and check its logs to find the issue.

Option B: ArgoCD deployment

If the

deployment.argocd

section is set in the manifest, generate the ArgoCD charts:


vpctl release generate --format argocd --clean-output

ArgoCD deploys from a Git repository. Commit the generated charts:


git add generated-charts/git commit -m "Add release charts"git push

Preview and run the deployment:


vpctl release deploy --format argocd --dry-runvpctl release deploy --format argocd

For all

release generate

and

release deploy

flags, refer to vpctl release.

7. Configure the DNS and certificates

Configure DNS records and TLS certificates for your domain to make the solution secure and accessible.

Register a fully qualified domain name (FQDN) for the frontend, for example,
```
example.com
```
.
Point the DNS record to the external IP or hostname of the Traefik load balancer. To find this information, run this command:
```
kubectl get svc -n <namespace> traefik
```
Configure a TLS certificate for the domain. You can use the Traefik ingress annotations in the manifest to reference your certificate, or configure it through your load balancer.

Troubleshooting

If a step fails, refer to vpctl troubleshooting for common issues and resolutions.

Next steps

Postdeployment

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Unity Cloud

Get Started

Asset Manager SDKs and services

Unity Cloud

Deploy the solution on premises

1. Configure the registry credentials

2. Initialize the manifest file

Validate the manifest

Configure the manifest file

3. Pull the release

4. Sync the artifacts

4.1 Authenticate to both registries

4.2 Run the preflight check

4.3 Sync the Docker images

4.4 Sync the ORAS artifacts

4.5 Sync the OCI Helm charts (preview, remote chart mode only)

5. Generate and deploy the secrets

Generate the secrets

Deploy the secrets

6. Generate and deploy the charts

Option A: Helm deployment

Verify the deployment

Option B: ArgoCD deployment

7. Configure the DNS and certificates

Troubleshooting

Next steps