Deploying Portal

Deploying Portal to a production environment

This guide highlights what to keep in mind when deploying Portal to a production environment.

Note: For those looking to explore Portal without deploying to production, you can run Portal locally. Read more here. Please be aware that any modifications made in the local instance of Portal cannot be transferred to your production environment.

Prerequisites

Before deploying Portal, you'll need to verify you can connect to backstage-api.spotify.com which is essential for the operation of Portal:

nc -vz backstage-api.spotify.com 443
Connection to backstage-api.spotify.com 443 port [tcp/https] succeeded!

If the connection test fails, follow these troubleshooting steps:

Check Firewall Settings: Ensure that no firewall is blocking access to port 443, which is used for HTTPS traffic.
Verify Network Configuration:
- Confirm that your network settings, including proxies and VPNs, allow connections to external HTTPS services.
- Use tools like ping and traceroute to diagnose connectivity issues.
Consult Network Logs: Check network logs for any blocked attempts or outgoing requests to identify if any additional configurations are necessary.
Contact Support: If you continue to experience issues, consider contacting your IT support team for help with network settings.

Kubernetes

Generate a secure password to be used to setup Portal for the first time

The password used by the root user is supplied using the PORTAL_ROOT_USER_PASSWORD environment variable.

Signing in as the root user is automatically disabled upon completion of setting up an authentication provider, however it's recommended to have a strong password here.
Generate secrets used for config encryption and backend authentication for the Soundcheck plugin

As documented here Portal requires a certain number of environment variables to be defined for it to successfully start.

The signing key for encrypting Portal's database content is supplied using the PORTAL_CONFIG_ENCRYPTION_KEY environment variable. It is required to be exactly 32 characters long.

It can be generated like this:
```
node -p 'require("crypto").randomBytes(32).toString("hex").substring(0,32)'
```
The signing key for Souncheck backend's auth is supplied using the PORTAL_SECRET_BACKEND_KEY environment variable. The key can be any base64 encoded secret and generated like this:
```
node -p 'require("crypto").randomBytes(24).toString("base64")'
```

Create a deployment

Use this Kubernetes Deployment descriptor template and make sure the <value> fields are substituted with real values.

Read more about secrets and environment variables here

# backstage-portal.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage-portal
  namespace: backstage-portal
spec:
  replicas: 1
  selector:
    matchLabels:
      app: backstage-portal
  template:
    metadata:
      labels:
        app: backstage-portal
    spec:
      containers:
        # Portal for Backstage
        - name: backstage-portal
          image: spotify/portal:<version>
          imagePullPolicy: IfNotPresent
          env:
            - name: PORTAL_BASE_URL
              value: <base-url>
            - name: PORTAL_SECRET_BACKEND_KEY
              value: <backend-key>
            - name: PORTAL_DATABASE_HOST
              value: localhost
            - name: PORTAL_DATABASE_PORT
              value: '5432'
            - name: PORTAL_DATABASE_USER
              value: <postgres-user>
            - name: PORTAL_SECRET_DATABASE_PASSWORD
              value: <postgres-password>
            - name: PORTAL_CONFIG_ENCRYPTION_KEY
              value: <encryption-key>
            - name: PORTAL_ROOT_USER_PASSWORD
              value: <root-password>
          ports:
            - name: http
              containerPort: 7007
              protocol: TCP
        # Postgres database sidecar
        - name: database
          image: postgres:13
          env:
            - name: POSTGRES_USER
              value: <postgres-user>
            - name: POSTGRES_PASSWORD
              value: <postgres-password>
            - name: POSTGRES_DB
              value: <postgres-database>
          ports:
            - name: postgres
              containerPort: 5432
              protocol: TCP

Applying that Deployment to a Kubernetes cluster 🎉
```
kubectl apply -f backstage-portal.yaml
```

Continue with the official documentation on how to learn more about deploying to Kubernetes.

System Requirements for Running Portal

To ensure Portal runs reliably, we provide both minimum and recommended system configurations:

Minimum Requirements

CPU: At least 1 CPU core.
Memory: At least 2 GB of RAM.

Recommended Configuration

CPU: 2 CPU cores.
Memory: 4 GB of RAM.

These specifications are designed to support the basic operations of Portal. For environments expecting higher traffic, consider scaling these resources to meet increased demands.

External Connectivity

Telemetry

Portal collects limited telemetry for product improvement purposes on an opt-in basis. You can opt out by visiting <baseURL>/config-manager/telemetry#root-portal-telemetry__title and unselecting "enable":

Config Manager Telemetry

Obtaining a License Key

To use Portal, you must obtain a license key.