LOCKNKEY – INSTALLATION GUIDE
Version: MVP
Last Updated: 2025-09-29

--------------------------------------------------
OVERVIEW
--------------------------------------------------
This document provides step-by-step instructions for installing and running
the LockNKey Quantum-Resistant Password Manager in a local development
environment. The installation uses Docker, Supabase, Node.js, and Python.

--------------------------------------------------
SYSTEM REQUIREMENTS
--------------------------------------------------
- Operating System: Windows, macOS, or Linux
- Docker Desktop (with Docker Compose enabled)
- Node.js version 18 or later
- Python version 3.11 or later
- Git
- Bash shell (Linux/macOS, Git Bash, or WSL on Windows)
- Web browser (Chrome, Firefox, Edge)

--------------------------------------------------
PROJECT STRUCTURE
--------------------------------------------------
The project root directory contains the following important folders:

- frontend/        Next.js web application
- backend/         Backend services (Vault and Quantum services)
- supabase/        Database configuration and migrations
- scripts/         Automation scripts
- Code/            Full source code and documentation

--------------------------------------------------
INSTALLATION STEPS
--------------------------------------------------

STEP 1: Clone the Repository
--------------------------------------------------
Open a terminal and run:

git clone https://github.com/CD0minguez/Lock-and-Key-Encrypted-Password-Management-and-Collaboration-System.git
cd Lock-and-Key-Encrypted-Password-Management-and-Collaboration-System

--------------------------------------------------
STEP 2: Verify Prerequisites
--------------------------------------------------
Ensure the following commands are available:

docker --version
docker-compose --version
node --version
python --version

If any are missing, install them before proceeding.

--------------------------------------------------
STEP 3: Start the Application (Recommended Method)
--------------------------------------------------
From the project root directory, run:

./start-app.sh

This script performs the following actions:
- Starts Supabase services
- Starts backend services using Docker Compose
- Starts the frontend Next.js development server
- Displays service URLs and status

--------------------------------------------------
STEP 4: Verify Running Services
--------------------------------------------------
Open a browser and verify the following URLs:

Frontend:        http://localhost:3000
Vault Service:   http://localhost:8002
Quantum Service: http://localhost:8001
Auth Service:    http://localhost:8003
Supabase Studio: http://localhost:54323
Email Testing:   http://localhost:54324

If the frontend loads successfully, the installation is complete.

--------------------------------------------------
STOPPING THE APPLICATION
--------------------------------------------------
To stop all services, run:

./stop-app.sh

--------------------------------------------------
RESTARTING THE APPLICATION
--------------------------------------------------
To restart all services, run:

./restart-app.sh

--------------------------------------------------
ENVIRONMENT CONFIGURATION
--------------------------------------------------
Environment variables are defined using template files:

- .env.example
- frontend/.env.local (generated during setup)

Modify these files if ports or service URLs need to be changed.

--------------------------------------------------
TROUBLESHOOTING
--------------------------------------------------
1. Port already in use:
   - Stop conflicting services or update ports in docker-compose files.

2. Services not updating after code changes:
   - Rebuild Docker images using:
     docker-compose build --no-cache
     docker-compose up -d

3. Supabase not running:
   - Ensure Supabase services start before backend services.

--------------------------------------------------
END OF INSTALLATION GUIDE
--------------------------------------------------
