Installation
AppSec Portal deployment step-by-step guide
Last updated
AppSec Portal deployment step-by-step guide
Last updated
Minimum system resources: 4 GB of RAM and 2 CPU cores.
Recommended system resources for 500-700 assets: 16 GB of RAM and 4 CPU cores.
Free disk space for installation and data storage of the portal.
Network access for external users (users must be able to connect to the portal over the network).
Before installing the AppSec Portal, make sure you have the following software installed on your machine (for Docker-compose installation type):
Docker (version 19.03 or higher)
Docker Compose (version 1.26 or higher)
SSH keys (for GitLab CI installation option)
To securely connect to the Linux server, you will need to set up SSH keys.
If you don't have SSH keys already, you can generate them using the following command in your server terminal:
ssh-keygen ⚠️ When copying keys, make sure you copy without spaces.
After generating the SSH keys, you need to copy the public SSH key to the Linux server. Use this command to copy the public key:
ssh-copy-id <username>@<server-ip-address>Replace <username> with your Linux server account username, and <server-ip-address> with the IP address of the Linux server. You will be prompted to enter your password for authentication.
Open the file on your local machine where the private SSH key is stored. The private key is typically saved with a .pem or .ssh file extension.
Select and copy the contents of the private key file. Ensure you copy the key with the correct permissions and line breaks intact.
Please note that the AppSec Portal is currently incompatible with Amazon Aurora database.
Option 1: GitLab CI installation (automated docker-compose installation)
Option 2: Install using Helm (install in Kubernetes environment)
Option 3: Docker compose installation (manual docker compose installation)
Step 1: Fork the AppSec Portal repository. This will create a copy of the repository under your account, which you can then modify and configure as needed
Step 2: Set the public SSH key on the host where the portal will be deployed. Add an SSH key to your GitLab account This key will be used to establish a secure connection between the host and the repository
Step 3: Configure Environment Variables for a forked project in GitLab CI/CD settings
mandatory environment variables that must be specified (In the CI/CD settings, you need to set the following environment variables for these keys):
SEC_PORTAL_HOST: Specify the host where the portal will be deployed SSH_KEY_PRIVATE: Set the private SSH key within the forked repository. This key will be used for authentication during the installation process
optional environment variables. You can choose to accept the default values provided for demonstration purposes or specified it if necessary:
IMAGE_VERSION=latest
DB_NAME=db_name
DB_USER=db_user
DB_PASS=db_pass
DB_HOST=db_host
DB_PORT=5432
GUNICORN_WORKERS=4
GUNICORN_THREADS=4
IMPORTER_GUNICORN_WORKERS=1
IMPORTER_GUNICORN_THREADS=1
RABBITMQ_DEFAULT_USER=admin
RABBITMQ_DEFAULT_PASS=mypass
AMQP_HOST_STRING=amqp://admin:mypass@rabbitmq:5672/
DOMAIN=http://localhost
COOKIES_SECURE=False (True if you use https)
The IMAGE_VERSION The script will autonomously determine the most recent version
For optimal performance (tested on 1 million findings), it is recommended to specify the following environment values: GUNICORN_WORKERS = 4 and GUNICORN_THREADS= 4 To configure the import worker and import threads, the following is necessary: IMPORTER_GUNICORN_WORKERS determines the number of workers for processing import tasks. It is recommended to set a value that takes into account the volume and intensity of import tasks. IMPORTER_GUNICORN_THREADS defines the number of threads within each import worker. This affects the parallel processing of tasks within the worker.
DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT variables are required for database configuration
If the message broker is hosted on a third-party server, only the AMQP_HOST_STRING must be specified. However, if the container is raised locally, all three variables, including RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS need to be specified. The username and password in the RABBITMQ_DEFAULT_PASS and RABBITMQ_DEFAULT_USER variables must be the same as in AMQP_HOST_STRING.
The COOKIES_SECURE variable determines the cookie security flag. It should be set to True if HTTPS is used.
Step 4: Run pipeline
Step 5: Click on install section
The GitLab CI script provided in the forked repository will handle the installation process
This script will raise the portal and generate a user with administrator privileges using the default login and password credentials "admin/admin"
Please note that after the initial installation, it is necessary to reset the password for the administrator user via the Django admin panel: follow the <your-domain>.com/admin URL and sign in using the superuser credentials, then select "Users" in the left panel. You can add users from there
Before using Helm, make sure that Helm is installed on your computer and that your Kubernetes cluster is configured to work with Helm
Step 1: Add helm package
Add the Appsec portal package to your server:
helm repo add appsecportal https://gitlab.com/api/v4/projects/37960926/packages/helm/stableStep 2: Set environment variables
change the default environment variables to meet your requirements :
Release name:
global.image.tag=release_v24.08.4Jira Webhook:
webhook.ingress.path="/api/v1/jira-helper/jira-event/<your-webhook>/"Replace your-webhook in path variable '/api/v1/jira-helper/jira-event/your-webhook/' with the unique identifier (token) associated with the specific webhook event, for example, e2b7e8be-1c77-4969-9105-58e91bd311cc.
Variables:
configs.configMap.cookies_secure="True"
configs.configMap.database.host="postgres"
postgresql.containerPorts.postgresql="5432"
postgresql.auth.database="postgres"
postgresql.auth.username="postgres"
configs.configMap.debug="True"
configs.configMap.domain="http://localhost"
rabbitmq.auth.username="admin" configs.configMap.cookies_secure: variable determines the cookie security flag. It should be set to True if HTTPS is used.
configs.configMap.database.host, postgresql.containerPorts.postgresql, postgresql.auth.database, postgresql.auth.username, and postgresql.auth.password specify the variables needed to configure the database, or use the defaults.
The configs.configMap.domain specify the domain where the Appsec-portal will be accessible.
if the container is raised locally rabbitmq.auth.username need to be specified
Secrets:
rabbitmq.containerPorts.amqp="amqp://admin:mypass@rabbitmq:5672/"
postgresql.auth.password="postgres"
configs.secret.jwt_private_key=<your key>
configs.secret.jwt_public_key=<your key>
configs.secret.secret_key=<your key>
rabbitmq.auth.password="mypass"If the message broker is hosted on a third-party server, only the rabbitmq.containerPorts.amqp must be specified. However, if the container is raised locally, all three variables, including rabbitmq.auth.username and rabbitmq.auth.password need to be specified
The configs.secret.jwt_private_key and configs.secret.jwt_public_key variables are RSA key pair used to sign JWT keys
configs.secret.secret_key: variable is used to generate hashes in Django
Note: Make sure that all of these variables are correctly substituted into the helm install portal appsecportal/appsecportal command
Step 3: Helm install with all resources inside cluster
In the example we use pre-installed nginx ingress controller and postgres, rabbitmq from chart:
helm install portal appsecportal/appsecportal --set postgresql.enabled=true
--set ingress.enabled=true --set ingress.annotations."nginx\.ingress\.kubernetes\.io\/scheme"=internet-facing
--set ingress.annotations."nginx\.ingress\.kubernetes\.io\/target\-type"=ip --set ingress.ingressClassName=nginx
--set ingress.host=your_own_host -n <namespace>
Step 4: Create a superuser account
To create an administrator account, execute the following command:
kubectl get pods -n <namespace>
kubectl exec -it -n <namespace> <portal_pod> -c appsecportal-backend -- /bin/sh
python3 manage.py createsuperuser --username adminThis username and password will allow you to log in to the installed Appsec Portal
Step 1: Clone the repository
Clone the AppSec Portal repository to your server:
git clone https://gitlab.com/whitespots-public/appsec-portal.git appsec-portalStep 2: Navigate to the root directory
Navigate to the root directory of the AppSec Portal project by executing the following command:
cd appsec-portalStep 3: Set environment variables
In the root directory of the AppSec Portal project, execute the following command:
./set_vars.shThe script prompts you for values for the following environment variables, including optional ones. You can also accept the default values for optional variables by pressing Enter:
DB_NAME{default=postgres}
DB_USER{default=postgres}
DB_PASS{default=postgres}
DB_HOST{default=postgres}
DB_PORT{default=5432}
RABBITMQ_DEFAULT_USER{default=admin}
RABBITMQ_DEFAULT_PASS{default=mypass}
AMQP_HOST_STRING{default=amqp://admin:mypass@rabbitmq:5672/}
COOKIES_SECURE{default=True}
DOMAIN=http://localhost
IMAGE_VERSION=release_v24.08.4
The IMAGE_VERSION the required variable must be specified. Specify a specific version, e.g. release_v24.08.4
The DOMAINthe required variable must be specified. Specify the domain where the AppSec Portal will be accessible
DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT optional variable. Specify the variables needed to configure the database, or use the defaults.
If the message broker is hosted on a third-party server, only the AMQP_HOST_STRING must be specified. However, if the container is raised locally, all three variables, including RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS need to be specified
The username and password in the RABBITMQ_DEFAULT_PASS and RABBITMQ_DEFAULT_USER variables must be the same as in AMQP_HOST_STRING.
The COOKIES_SECURE variable determines the cookie security flag. It should be set to True if HTTPS is used
The set_vars.sh script creates the .env file with the configured environment variables and generates a pair of JWT keys, which are used to sign JWT keys and SECRET_KEY is used to generate hashes in Django.
DO NOT run the ./set_vars.sh command twice. If you need to change the value of a variable, do so in the .env file.
Step 4: Start the AppSec Portal
To start the AppSec Portal, run the following command:
sh run.shStep 5: Create a superuser account
To create an administrator account, execute the following command:
docker compose exec back python3 manage.py createsuperuser --username adminThis username and password will allow you to log in to the installed Appsec Portal
or
Create users using Django admin panel
In order to access admin settings, follow the <your-domain>.com/admin URL and sign in using the superuser credentials, then select Users in the left panel. You can add users from there. Don't forget to assign the necessary permissions to the users.
Congratulations, you have successfully installed the AppSec Portal! Now apply the licence to your installed application.
If you have any issues during the installation process or while using the app, contact our support team sales@whitespots.io for assistance❤️.
