Developer Setup
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the necessary steps and architecture for setting up and running the llama-leaks project in a local development environment. The project is a public security awareness dashboard designed to highlight unintentionally exposed Ollama AI servers. It consists of a Python backend for data handling and a React-based frontend for data visualization and user interaction.
The core mission is to passively monitor and display information about these exposed servers in an educational manner, encouraging better security practices within the AI development community.
Sources: README.md, frontend/src/pages/About.tsx:49-54
System Architecture
The application is a classic client-server model, composed of two main parts: a backend service and a frontend web application.
This diagram shows the high-level developer workflow. The run_dev.sh script orchestrates the startup of both the backend and frontend services.
Sources: run_dev.sh, backend/requirements.txt, frontend/package.json
Prerequisites
Before starting, ensure you have the following installed on your system:
- Node.js and npm: Required for the frontend application.
- Python and pip: Required for the backend service.
- A Unix-like shell (e.g., bash): To execute the
run_dev.shscript.
Sources: run_dev.sh, backend/requirements.txt, frontend/package.json
Backend Setup
The backend is a Python application. Its dependencies are managed via pip and are listed in the backend/requirements.txt file.
To set up the backend, you would typically navigate to the backend directory and run:
pip install -r requirements.txt
The run_dev.sh script automates this process. The specific dependencies are not detailed in the provided files, but they are installed from this file.
Sources: run_dev.sh, backend/requirements.txt
Frontend Setup
The frontend is a modern web application built with React, Vite, and TypeScript. It uses Tailwind CSS for styling and Shadcn/ui for its component library.
Sources: frontend/package.json:1,10,87,90
Dependencies
The frontend relies on a number of libraries for its functionality. Key dependencies are listed in frontend/package.json.
| Dependency | Version | Description |
|---|---|---|
react | ^18.3.1 | A JavaScript library for building user interfaces. |
vite | ^5.4.1 | A build tool that aims to provide a faster and leaner development experience. |
tailwindcss | ^3.4.11 | A utility-first CSS framework for rapid UI development. |
typescript | ^5.5.3 | A typed superset of JavaScript that compiles to plain JavaScript. |
react-router-dom | ^6.26.2 | Client-side routing for React applications. |
@tanstack/react-query | ^5.56.2 | Data-fetching and state management library. |
lucide-react | ^0.462.0 | A library of simply beautiful icons. |
mapbox-gl | ^3.13.0 | A library for interactive, customizable vector maps on the web. |
Sources: frontend/package.json:15-81
Scripts
The frontend/package.json file defines several scripts for managing the development lifecycle.
| Script | Command | Description |
|---|---|---|
dev | vite | Starts the Vite development server with Hot Module Replacement (HMR). |
build | vite build | Compiles the TypeScript and React code into static assets for production. |
lint | eslint . | Lints the codebase to find and fix problems in the code. |
preview | vite preview | Serves the production build locally to preview it before deployment. |
Sources: frontend/package.json:6-9
Application Entry Point
The frontend application's HTML entry point is frontend/index.html. This file sets up the basic document structure, includes metadata for SEO and social sharing, and links the main application script.
<!-- frontend/index.html:23-24 -->
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
The React application is mounted into the <div id="root"></div> element.
Sources: frontend/index.html:23-24
Running the Application in Development Mode
The run_dev.sh script is the primary tool for starting the entire application stack for local development.
Execution Flow
The script automates the setup and execution of both the backend and frontend services.
This flowchart illustrates the sequence of commands executed by the run_dev.sh script.
Sources: run_dev.sh
Development-Specific Features
The frontend code includes logic that behaves differently in development versus production. For example, the main page dynamically loads a SentryTestButton component only when the application is running in a development environment.
// frontend/src/pages/Index.tsx:11-14
// Dynamically import SentryTestButton only in development
const SentryTestButton =
process.env.NODE_ENV === "development"
? lazy(() => import("@/components/SentryTestButton"))
: () => null;
// frontend/src/pages/Index.tsx:40-46
{/* Remove this in production */}
{process.env.NODE_ENV === 'development' && (
<Suspense fallback={<div>Loading...</div>}>
<div className="fixed bottom-4 right-4 z-50">
<SentryTestButton />
</div>
</Suspense>
)}
This pattern ensures that debugging tools or test components are not included in the final production build, optimizing performance and security.
Sources: frontend/src/pages/Index.tsx:11-14, 40-46
Data Fetching
In the development environment, the frontend fetches data from local JSON files to simulate the backend API. The LocationInfo component, for instance, fetches server data from /data/live_servers.json.
This diagram shows the sequence for fetching and displaying a random exposed server on the frontend.