Running locally

This guide focuses on running Portal in a local development setup. It is useful for those trying out Portal for the first time or just learning more about Portal in general.

For deploying Portal in a production environment, read more here.

Prerequisites

• Docker Compose to run the Spotify Portal for Backstage docker image and its dependencies.

Running Portal

It is recommended to use Docker Compose when running Portal locally, as it greatly simplifies connecting it to a Postgres database.

1. Copy the following yaml into a file called docker-compose.local.yaml:

   note

   To test Portal locally the latest is or you can find other versions in the Portal Docker Hub repository. Then use that value to replace <latest-version> in the example below.

   version: '3'
   
   services:
     db:
       image: postgres:13
       environment:
         POSTGRES_DB: postgres
         # Database credentials
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: postgres
       healthcheck:
         test: ['CMD', 'pg_isready', '-U', 'postgres']
         interval: 5s
         timeout: 5s
         retries: 5
   
     backstage:
       image: 'spotify/portal:<latest-version>'
       environment:
         # Reference database service
         PORTAL_DATABASE_HOST: db
         PORTAL_DATABASE_PORT: 5432
         PORTAL_DATABASE_USER: postgres
         PORTAL_SECRET_DATABASE_PASSWORD: postgres
   
         # This is the password to sign in with for the first time.
         PORTAL_ROOT_USER_PASSWORD: root
   
         # This password is used to encrypt the Portal database. It needs to be a specific length.
         PORTAL_CONFIG_ENCRYPTION_KEY: ReplaceThisKeyIfUsedInProduction
   
         # This password is used for Soundcheck backend auth.
         PORTAL_SECRET_BACKEND_KEY: ReplaceThisKeyTooIfProd
   
         # This is the URL of the app.
         PORTAL_BASE_URL: 'http://localhost'
   
       ports:
         - '80:7007'
       depends_on:
         db:
           condition: service_healthy

2. Start the application

   docker compose -f docker-compose.local.yaml up

   If you want to stop the containers use the following command:

   docker compose -f docker-compose.local.yaml down

3. Login to Portal

   When the application has started up, open a browser and navigate to http://localhost. A sign-in page should appear.

   

   Use the password supplied for PORTAL_ROOT_USER_PASSWORD to sign in as the built-in authorized admin user root.

   Note that this password is set to plainly root in the compose file. It's strongly recommended to change this password, even if running locally.

Note: Once an authentication provider is properly configured this method of signing in will be disabled.