Troubleshooting

Fix the common problems of installing and running AppSec Portal, and find its logs.

Updated

Read the logs

Most problems show up in the logs of the back service first.

With Docker Compose, open sh launcher.sh in the install folder. The menu shows how many services are running, and Logs shows the logs of all services. Healer logs lists the services that were restarted because they stopped responding.

To run Compose commands yourself, load the install’s configuration first. The install folder has no single docker-compose.yml, so a plain docker compose doesn’t find the services:

bash
. ./.compose-config.sh
compose ps
compose logs --tail 200 back

compose ps shows which services aren’t running or are unhealthy. Imports run in importer and importer_worker, integrations and background jobs in the db_helper_* services.

With Helm:

bash
kubectl get pods -n portal
kubectl logs -n portal -l app.kubernetes.io/name=portal-portal --tail 200

Login fails right after the install

  • Login fails over plain HTTP. The domain starts with https, so COOKIES_SECURE is True and the browser doesn’t keep the session over HTTP. Set up HTTPS, or set COOKIES_SECURE=False in .env and choose Restart in sh launcher.sh (with Helm, set cookies_secure: false and run helm upgrade).
  • No user can log in. Check that you created the administrator. If you didn’t start Portal at the end of the install, the installer skipped it: open sh launcher.sh, then Settings → Create superuser.

The license doesn’t activate

To activate a license, the server sends the key to the license server over HTTPS. If outgoing connections go through a proxy or a firewall, allow HTTPS from the server.

With a paid license, Tech Radar also needs the license server after activation, so keep HTTPS to it open.

The techradar service keeps restarting

The techradar service runs only with an activated paid license, and only while it can reach the license server. Without one, it stops right after it starts, and Docker starts it again. The rest of Portal works. Activate a paid license, or check the network as described above.

Everyone is logged out and integrations stopped working

The signing keys changed: someone chose Regenerate keys in the launcher, reinstalled over the existing configuration, or copied a different .env. Sessions signed with the old keys end, and the credentials saved in integrations can’t be read any more.

Put the old JWT_PRIVATE_KEY, JWT_PUBLIC_KEY and SECRET_KEY back into .env if you have them, and restart. If you don’t, log in again and enter the credentials of each integration again.

Requests fail with “Bad Request” and imports hang

Check the free disk space on the server first:

bash
df -h
docker system df

When the disk is full, the message queue stops, and every request that waits for a background job fails. Free space, for example with docker image prune, then restart Portal.

If the disk isn’t full, the server may be short of memory or CPU. See the resource advice in Install.

Data is gone after a restart

  • Helm with the bundled PostgreSQL: older charts ran PostgreSQL without a volume. Current charts keep the data, and stop an upgrade of such an installation with an error that explains how to move the data to a volume.
  • Docker Compose: the database is in data/db in the install folder. Don’t delete that folder, and run the update commands from the same folder. Hard reset in the launcher’s Danger zone deletes it, together with the uploaded files, the backups and the settings.

The web interface doesn’t open

  • Docker Compose: nginx listens on ports 80 and 443. If another web server uses them, nginx fails to start: compose ps shows it as not running. Stop the other server or put it in front of Portal as a proxy.
  • Helm: check that the ingress controller is running and that ingress.host matches the address users open.