You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(deploy): Add Windows scripts and overhaul documentation
This commit standardizes the project's deployment strategy across platforms.
- Adds .bat scripts for Windows (start_production, start_development, stop_production) to mirror the existing .sh scripts.
- Completely rewrites the README.md with detailed, step-by-step setup instructions for both macOS/Linux and Windows.
- Removes the PyInstaller GitHub Actions workflow to focus on a single, robust 'run from source' deployment method.
**Sherlock is a comprehensive, self-hosted inventory and lending management system designed for school labs, makerspaces, and workshops.**
7
+
**Sherlock is a comprehensive, self-hosted inventory and lending management system designed for school labs, makerspaces, and workshops.** It provides a powerful, data-driven platform to track assets, manage student loans, and gain insight into your lab's operations, all accessible from any device on your network.
9
8
10
-
This project is a complete, ground-up rewrite and significant feature expansion of the original [Sherlock v1.0](https://github.com/Atal-Lab-DPSBS/Sherlock). It transforms the application from a simple inventory list into a powerful, data-driven lab management platform built on a modern and robust Python/Django backend.
9
+
This project is a complete, ground-up rewrite of the original [Sherlock v1.0](https://github.com/Atal-Lab-DPSBS/Sherlock), built on a modern and secure Python/Django backend.
11
10
12
11
---
13
12
@@ -17,79 +16,178 @@ This project is a complete, ground-up rewrite and significant feature expansion
The goal of Sherlock v2.0 is to provide a powerful, easy-to-deploy, and intuitive tool for lab managers to track their physical inventory. It answers the critical questions of lab management:
37
+
The goal of Sherlock v2.0 is to answer the critical questions of lab management:
35
38
***What** do we have and **where** is it?
36
-
***Who** has borrowed our equipment?
37
-
***When**is it due back?
38
-
***What**is our inventory's lifecycle?
39
+
***Who** has borrowed our equipment and **when** is it due back?
40
+
***How**are our resources being used over time?
41
+
***How**can we manage team access and security effectively?
39
42
40
43
## ✨ Core Features
41
44
42
45
### Inventory Management
43
46
***Hierarchical Structure:** Organize your inventory logically with **Sections**, **Spaces**, and **Items**.
44
-
***Stock Control:** A full, permanent audit trail for every stock change (e.g., "Received New Stock," "Reported Damaged").
45
-
***Label Printing:** Generate and print custom barcode and QR code labels to seamlessly bridge your physical and digital inventory.
46
-
***Unified Search:**A powerful, live-search dashboard to find any item or student record in the system.
47
+
***Complete Audit Trail:** A permanent log of every stock change (e.g., "Received New Stock," "Reported Damaged").
48
+
***Label Printing:** Generate and print custom barcode and QR code labels.
49
+
***Universal Scan:**Use any connected camera to instantly look up items, spaces, or sections from their labels.
47
50
48
51
### Advanced Lending System
49
-
***Student Records:** Maintain a secure database of students with filtering and search capabilities.
50
-
***Kiosk-Style Checkout Terminal:** A dedicated, fast interface for lending items, featuring a live, as-you-type search for both students and items.
51
-
***Stock Validation:** The system automatically checks available stock before allowing a checkout.
52
-
***Partial Returns & Loan History:** A sophisticated check-in system that allows for partial returns and keeps a complete, auditable log of every transaction for both students and items.
53
-
***Due Date & Overdue Tracking:** Assign a due date to every loan and get instant visibility on overdue items through the main dashboard and a dedicated report.
52
+
***Student Records:** Maintain a secure database of students.
53
+
***Kiosk-Style Checkout Terminal:** A dedicated, fast interface for lending items.
54
+
***Partial Returns & Condition Tracking:** A sophisticated check-in system that allows for partial returns and tracks the condition ("OK" or "Damaged") of returned items.
55
+
***Due Date & Overdue Tracking:** Assign due dates to every loan and get instant visibility on overdue items.
56
+
57
+
### Administration & Security
58
+
***Role-Based Access Control:** A two-tier user system (**Admin** and **Member**).
59
+
***Live Security Dashboard:** A "Team Management" page for Admins to view real-time user activity (**Online/Offline** status), suspend/reactivate accounts, and forcibly terminate user sessions.
60
+
***Secure by Default:** All network traffic is encrypted via HTTPS, enabling secure camera access from any device.
61
+
62
+
## 🚀 Getting Started: A Step-by-Step Guide
63
+
64
+
This guide will walk you through the one-time setup required to run Sherlock.
This project uses a virtual environment to manage its packages.
77
+
78
+
1.**Create and activate the virtual environment:**
79
+
***On macOS/Linux:**
80
+
```bash
81
+
python3 -m venv venv
82
+
source venv/bin/activate
83
+
```
84
+
***On Windows:**
85
+
```cmd
86
+
python -m venv venv
87
+
.\venv\Scripts\activate
88
+
```
89
+
2. **Install the required packages:**
90
+
```bash
91
+
pip install -r requirements.txt
92
+
```
93
+
94
+
### Step 3: Install Caddy Webserver
95
+
96
+
Caddy is a modern, secure web server that automatically handles HTTPS for us. This is **required**for the camera scanning feature to work on all devices on your network.
97
+
98
+
<details>
99
+
<summary><strong>🔵 For macOS / Linux</strong></summary>
100
+
101
+
The easiest way is to use a package manager.
102
+
***With Homebrew (macOS):**`brew install caddy`
103
+
***With `apt` (Debian/Ubuntu):** Follow the official instructions [here](https://caddyserver.com/docs/install#debian-ubuntu-raspbian).
104
+
105
+
After installation, verify it by opening a new terminal and running `caddy version`.
106
+
</details>
107
+
108
+
<details>
109
+
<summary><strong>
110
+
🪟 For Windows (Detailed Steps)
111
+
</strong></summary>
112
+
113
+
Setting up a command-line tool on Windows requires a few extra steps. Please follow these carefully.
114
+
115
+
1. **Download Caddy:**
116
+
* Go to the official download page: [**caddyserver.com/download**](https://caddyserver.com/download).
117
+
* Select the latest version for the **Windows amd64** platform.
118
+
* This will download a file named something like `caddy_2.x.x_windows_amd64.exe`.
119
+
120
+
2. **Unblock the File:**
121
+
* Windows automatically "blocks" executables downloaded from the internet. We must unblock it.
122
+
* Find the downloaded file in your Downloads folder, **right-click** it, and select**Properties**.
123
+
* At the bottom of the General tab, you should see a security warning. **Check the "Unblock" checkbox** and click **OK**.
54
124
55
-
### Modern Technology
56
-
***Camera Scanning:** Use your device's camera for rapid checkouts and to instantly look up any item, space, or section with the Universal Scan tool.
57
-
***Data Visualizations:** The main dashboard features charts for weekly loan activity and most popular items, providing instant insight into your lab's operations.
125
+
3. **Place and Rename the File:**
126
+
* Rename the file to `caddy.exe`.
127
+
* Create a new folder on your C: drive called `C:\Caddy`.
128
+
* Move `caddy.exe` into this `C:\Caddy` folder.
58
129
59
-
## 🚀 Deployment
130
+
4. **Add Caddy to the System PATH:**
131
+
* This is the most critical step. It allows you to run `caddy` from any terminal.
132
+
* Press the Windows key and search for**"Edit the system environment variables"**. Open it.
133
+
* In the window that appears, click the **"Environment Variables..."** button.
134
+
* In the bottom box, under "System variables," find and selectthe variable named **`Path`**.
135
+
* Click **"Edit..."**.
136
+
* Click **"New"** and typein the path to your new folder: `C:\Caddy`.
137
+
* Click **OK** on all three windows to save your changes.
60
138
61
-
Sherlock is designed for incredibly simple deployment. It is packaged as a **standalone executable** using PyInstaller, containing the entire application, web server, and all dependencies.
139
+
5. **Verify the Installation:**
140
+
***Close and reopen** your terminal (Command Prompt or PowerShell).
141
+
* Run the command`caddy version`. If it prints a version number, you have successfully installed Caddy!
62
142
63
-
### How to Run Sherlock:
64
-
1. Go to the [**Releases**](https://github.com/YOUR-USERNAME/Sherlock-python/releases) page of this repository.
65
-
2. Download the latest `.zip` file for your operating system (e.g., `Sherlock-v2.0.0-Windows.zip`).
66
-
3. Unzip the file and double-click the `Sherlock` executable.
143
+
</details>
67
144
68
-
The server will start, automatically creating a new database on the first run. The application will be available at `http://127.0.0.1:8000` and on your local network.
145
+
### Step 4: Run the Application
69
146
70
-
## 💻 For Developers: Running from Source
147
+
We provide simple scripts to handle both development and production modes.
71
148
72
-
1.**Clone the repository:**
149
+
#### Production Mode (Recommended)
150
+
151
+
This mode runs the secure HTTPS server, which is **required for camera scanning** to work across your network.
The script will start the Caddy and Waitress servers. You can then access Sherlock from any device at the `https://<your_ip_address>:8443` URL printed in the terminal.
163
+
164
+
>**⚠️ Browser Security Warning (First Time Only):**
165
+
> The first time you access the `https://` URL, your browser will show a security warning ("This Connection Is Not Private," etc.). This is normal and expected because the security certificate is self-signed by Caddy. **It is safe to proceed.** Click "Advanced,""Show Details," or "Visit this website" to continue. Your connection is fully encrypted.
166
+
>
167
+
>**Firewall Popup (First Time Only):**
168
+
> Your operating system's firewall (Windows Defender or macOS Firewall) will likely show a popup asking for permission for "Caddy" to accept network connections. You **must click "Allow"** for other devices to be able to connect to the server.
169
+
170
+
#### Development Mode
171
+
172
+
This mode runs a simpler HTTP server. Camera access will **only** work when accessing the site from `http://localhost:8000` on the same machine.
0 commit comments