Getting Started
===============


This guide will help you get VulnerabilityHub up and running on your system.

Prerequisites
-------------


System Requirements
~~~~~~~~~~~~~~~~~~~

- **OS**: Linux (Ubuntu 20.04+, Debian 11+, or similar)
- **RAM**: Minimum 4GB, recommended 8GB+
- **Disk**: 20GB+ free space
- **CPU**: 2+ cores recommended

Software Dependencies
~~~~~~~~~~~~~~~~~~~~~

- Docker 20.10+
- Docker Compose 2.0+
- Git

Installation
------------

1. Clone the Repository
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   git clone <repository-url>
   cd vulnerability-scanner


2. Configure Environment Variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Adapt the example configuration file (.env)

See :doc:`configuration` for a detailed list of all available options.


3. Start the Application
~~~~~~~~~~~~~~~~~~~~~~~~

Start all services using Docker Compose:

.. code-block:: bash

   docker-compose up -d

This will start:
- **Backend API** (port 8000)
- **Frontend** (port 80)
- **Database** (port 3306)
- **Grafana** (port 3000)
- **Prometheus** (port 9090)
- **ClamAV** (Antivirus service)


Initialization
--------------

Create Admin User
~~~~~~~~~~~~~~~~~

Navigate to the frontend at http://localhost:80
On inital setup you will be asked to create an admin account.
You can configure the credentials freely but need to stick to the password requirements documented in :ref:`Changing-Password`

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For development or testing, use the demo data script. This creates:
- Admin user (`admin` / `DemoPass123!`)
- Sample users (`prof_mueller`, `dr_schmidt`, `user_bib`, etc.)
- Contact persons & Institutions
- Sample scans with vulnerabilities and historical trend data
- Configured email templates

.. code-block:: bash

   docker-compose exec backend python3 generate_demo_data.py


Troubleshooting
---------------

**Database Connection Failed**
    Ensure the `db` container is healthy: ``docker-compose ps db``. Check logs: ``docker-compose logs db``.

**Rate Limiting Errors**
    If you hit API limits ("429 Too Many Requests"), adjust ``RATE_LIMIT_PER_MINUTE`` in your ``.env`` file or restart the backend to clear in-memory limits.