Install

Install AppSec Portal with Docker Compose or Helm, activate the license and create the first user.

Updated

Install AppSec Portal in one of two ways:

  • Docker Compose on one Linux server. This is the simplest way.
  • Helm in a Kubernetes cluster.

Before you start

  • A license key. Sign up at https://whitespots.io/store. A free license comes with every account.
  • A server that users can reach over the network. The resources it needs depend on how many assets you have and how many scan results you send. Start with at least 8 CPU cores and 16 GB of RAM, watch the usage, and add more when imports or pages slow down.
  • A database. Both ways can run PostgreSQL for you, or use your own PostgreSQL server. Amazon Aurora isn’t supported.

Docker Compose

You need Docker with the Compose plugin (docker compose), git, bash, openssl, curl and jq on the server.

  1. Download the install files:

    bash
    git clone https://gitlab.com/whitespots-public/appsec-portal.git portal
cd portal

  2. Start the launcher:

    bash
    sh launcher.sh

    The first time, the launcher runs the installer. It asks for:

    • Where the services run: the message broker (Redis or RabbitMQ) and PostgreSQL can run next to Portal, or you can use your own servers. Press Enter to keep the defaults: Redis and PostgreSQL in containers, no log forwarding.
    • The settings: the database name, user and password, and the domain. The domain is the address users open, with the scheme, for example https://portal.example.com. Change the default database password. With your own servers, enter their addresses.

    The installer installs the latest release, generates new signing keys and downloads the images. Then it starts Portal and asks for the user name and password of the first administrator. The first start takes a few minutes. The web interface listens on ports 80 and 443.

    The settings are saved to .env and .compose-config.sh. Keep a copy of both: you need them to move the database.

  3. From now on, sh launcher.sh opens a menu to run, stop, update and back up Portal, and to read its logs. To change a setting, open Settings.

Helm

You need Helm 3, a cluster with Kubernetes 1.19 or later, and an ingress controller.

  1. Add the chart repository:

    bash
    helm repo add portal https://gitlab.com/api/v4/projects/37960926/packages/helm/stable
helm repo update

  2. Generate the signing keys. The chart has none built in, and the install fails without them.

    bash
    openssl genrsa -out jwt-private.pem 2048
openssl rsa -in jwt-private.pem -pubout -out jwt-public.pem
pem() { awk 'NR > 1 { printf "\\n" } { printf "%s", $0 }' "$1"; }
cat > secrets.yaml <<EOF
configs:
  secret:
    jwt_private_key: '$(pem jwt-private.pem)'
    jwt_public_key: '$(pem jwt-public.pem)'
    secret_key: '$(openssl rand -hex 32)'
EOF

    Keep secrets.yaml safe. Sessions are signed and integration credentials are encrypted with these keys, and you need the file to move Portal to another cluster.

  3. Write the settings to values.yaml:

    yaml
    configs:
  configMap:
    domain: https://portal.example.com
    cookies_secure: true
ingress:
  ingressClassName: nginx
  host: portal.example.com

    • domain is the address users open, with the scheme. Set cookies_secure to false when users open it over plain HTTP.

    • The chart runs PostgreSQL in the cluster and keeps its data on a volume. For production, use your own PostgreSQL server instead:

      yaml
      postgresql:
  enabled: false
externalPostgresql:
  enabled: true
  host: postgres.example.com
  port: "5432"
  database: portal
  username: portal
  password: <password>

    • Redis also runs in the cluster. To use your own, set redis-ha.enabled: false and fill in externalRedis.

    All settings are in the chart’s values.yaml in the install repository.

  4. Install it:

    bash
    helm upgrade --install portal portal/portal \
  -n portal --create-namespace \
  -f values.yaml -f secrets.yaml

    The database migrations run as a job after the install.

  5. Create the first administrator:

    bash
    kubectl exec -it -n portal \
  $(kubectl get pods -n portal -l app.kubernetes.io/name=portal-portal -o jsonpath='{.items[0].metadata.name}') \
  -- python manage.py createsuperuser --username admin

If the cluster has no ingress controller yet, install one, for example ingress-nginx.

Activate and log in

Open the domain in a browser. AppSec Portal asks for the license first: paste the key into Activate License and click Activate. Then log in with the administrator you created.

Next, install Auditor to run the scanners, then see First steps.