Skip to content

Commit b00040e

Browse files
JarshiganKJarshiganK
committed
Update Usermanual
1 parent 5a416ab commit b00040e

File tree

4 files changed

+196
-1122
lines changed

4 files changed

+196
-1122
lines changed

‎README.md‎

Lines changed: 195 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ EventStack is a robust full-stack event management platform designed to connect
99
- **Event Discovery**: Users can browse, search, and view detailed information about events.
1010
- **Bookmarking**: Attendees can save events they are interested in.
1111
- **Expense Tracking**: Organizers can manage event budgets and track expenses.
12-
- **AI-Powered Budget Bot**: An intelligent assistant to help with budget planning.
12+
- **AI-Powered Budget Bot**: An intelligent assistant to help with budget planning (requires Gemini API key).
1313
- **Admin & Organizer Dashboards**: Dedicated interfaces for managing events and finances.
1414

1515
## 🛠️ Tech Stack
@@ -41,112 +41,241 @@ eventstack/
4141
├── apps/
4242
│ ├── backend/ # Fastify server, database logic, and API endpoints
4343
│ └── frontend/ # React client application and UI components
44+
├── deploy-eventstack.ps1 # Automated deployment script
4445
├── tsconfig.base.json
4546
└── README.md
4647
```
4748

4849
## 🚀 Getting Started
4950

50-
To get a local copy up and running, follow these steps.
51-
5251
### Prerequisites
5352

5453
- [Node.js](https://nodejs.org/) (v20.x or later)
5554
- [npm](https://www.npmjs.com/)
5655
- [PostgreSQL](https://www.postgresql.org/download/)
56+
- [PowerShell](https://learn.microsoft.com/en-us/powershell/) (for automated deployment on Windows)
57+
58+
### Quick Start (Automated Deployment)
59+
60+
The easiest way to set up EventStack is using the automated PowerShell deployment script. This script handles database setup, environment configuration, dependency installation, and server startup automatically.
61+
62+
1. **Clone the Repository**:
63+
```sh
64+
git clone <YOUR_REPOSITORY_URL>
65+
cd eventstack
66+
```
67+
68+
2. **Run the Deployment Script**:
69+
```powershell
70+
.\deploy-eventstack.ps1
71+
```
72+
73+
The script will:
74+
- Check for required tools (psql, npm, node)
75+
- Create the database if it doesn't exist
76+
- Apply the database schema
77+
- Create/update the backend `.env` file
78+
- Install dependencies for both backend and frontend
79+
- Start both servers in separate windows
80+
81+
**⚠️ Security Warning**: The script uses default values for database password and JWT secret. **You should override these in production or for any shared environment.**
82+
83+
3. **Deployment Script Parameters**:
84+
85+
The script accepts the following parameters with their default values:
86+
87+
**Database Configuration**:
88+
- `-DbName` (default: `eventstack`) - PostgreSQL database name
89+
- `-DbHost` (default: `localhost`) - PostgreSQL server host
90+
- `-DbPort` (default: `5432`) - PostgreSQL server port
91+
- `-DbUser` (default: `postgres`) - PostgreSQL username
92+
- `-DbPassword` (default: `Changeme`) - **⚠️ Change this default password!**
93+
94+
**Server Configuration**:
95+
- `-BackendHost` (default: `localhost`) - Backend server host
96+
- `-BackendPort` (default: `4000`) - Backend server port
97+
- `-FrontendHost` (default: `localhost`) - Frontend server host
98+
- `-FrontendPort` (default: `5173`) - Frontend server port
99+
100+
**Security Configuration**:
101+
- `-JwtSecret` (default: `change-me-now`) - **⚠️ Change this default JWT secret!**
102+
- `-CorsOrigins` (default: `http://localhost:5173`) - Comma-separated CORS origins
103+
104+
**Deployment Options** (switches):
105+
- `-SkipDb` - Skip database setup
106+
- `-SkipBackend` - Skip backend installation and startup
107+
- `-SkipFrontend` - Skip frontend installation and startup
108+
- `-LoadSampleData` - Load sample data into the database
109+
- `-ProdFrontend` - Build and serve production frontend (instead of dev server)
110+
111+
4. **Customize Deployment** (examples):
112+
```powershell
113+
# Override default password and JWT secret (RECOMMENDED)
114+
.\deploy-eventstack.ps1 -DbPassword "YourSecurePassword123" -JwtSecret "your-super-secret-jwt-key-min-6-chars"
115+
116+
# Custom database settings
117+
.\deploy-eventstack.ps1 -DbName "myeventstack" -DbUser "myuser" -DbPassword "mypassword"
118+
119+
# Custom ports
120+
.\deploy-eventstack.ps1 -BackendPort 5000 -FrontendPort 3000
121+
122+
# Load sample data
123+
.\deploy-eventstack.ps1 -LoadSampleData
124+
125+
# Multiple customizations
126+
.\deploy-eventstack.ps1 -DbPassword "SecurePass" -JwtSecret "MySecretKey" -BackendPort 8080 -LoadSampleData
127+
128+
# Skip specific steps (useful for partial deployments)
129+
.\deploy-eventstack.ps1 -SkipDb -SkipBackend
130+
131+
# Production frontend build
132+
.\deploy-eventstack.ps1 -ProdFrontend
133+
134+
# Custom CORS origins (for multiple frontend instances)
135+
.\deploy-eventstack.ps1 -CorsOrigins "http://localhost:5173,http://localhost:3000"
136+
```
137+
138+
For all available options, run:
139+
```powershell
140+
Get-Help .\deploy-eventstack.ps1 -Full
141+
```
142+
143+
5. **Cleanup**: When you're done, press `ENTER` in the deployment script window to clean up services and optionally drop the database. Press `CTRL+C` to exit without dropping the database.
144+
145+
**Important Security Notes**:
146+
- The default database password (`Jarshi17225`) and JWT secret (`change-me-now`) are **not secure** and should be changed for any non-local development environment.
147+
- Always use strong, unique passwords and JWT secrets in production.
148+
- The JWT secret must be at least 6 characters long.
149+
150+
### Manual Setup
151+
152+
If you prefer to set up the project manually or are on a non-Windows system:
57153

58-
### 1. Clone the Repository
154+
#### 1. Clone the Repository
59155

60156
```sh
61157
git clone <YOUR_REPOSITORY_URL>
62158
cd eventstack
63159
```
64160

65-
### 2. Database Setup
161+
#### 2. Database Setup
66162

67-
1. Make sure your PostgreSQL server is running.
68-
2. Create a new database for the project.
69-
3. Execute the schema and sample data scripts to initialize your database:
70-
- Run the contents of `apps/backend/database/schema.sql` to create the tables.
71-
- (Optional) Run the contents of `apps/backend/database/sample_data.sql` to populate the database with initial data.
163+
1. Make sure your PostgreSQL server is running.
164+
2. Create a new database:
165+
```sh
166+
createdb eventstack
167+
```
168+
3. Apply the schema:
169+
```sh
170+
psql -d eventstack -f apps/backend/database/schema.sql
171+
```
172+
4. (Optional) Load sample data:
173+
```sh
174+
psql -d eventstack -f apps/backend/database/sample_data.sql
175+
```
72176

73-
### 3. Environment Configuration
177+
#### 3. Environment Configuration
74178

75-
The backend requires environment variables to connect to the database and manage security settings.
179+
Navigate to the backend directory and create a `.env` file:
76180

77-
1. Navigate to the backend directory:
78-
```sh
79-
cd apps/backend
80-
```
81-
2. Create a `.env` file by copying the example:
82-
```sh
83-
# You may need to create this file
84-
touch .env
85-
```
86-
3. Add the following required environment variables to the `.env` file. Replace the placeholder values with your actual configuration.
181+
```sh
182+
cd apps/backend
183+
```
87184

88-
```env
89-
# PostgreSQL Connection URL
90-
DATABASE_URL="postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME"
185+
Create a `.env` file with the following variables:
91186

92-
# JWT Secret for signing tokens
93-
JWT_SECRET="your-super-secret-jwt-key"
187+
```env
188+
NODE_ENV=development
189+
PORT=4000
190+
DATABASE_URL="postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME"
191+
JWT_SECRET="your-super-secret-jwt-key-minimum-6-characters"
192+
CORS_ORIGINS="http://localhost:5173"
193+
GEMINI_API_KEY="" # Optional: Required for AI Budget Bot features
194+
```
94195

95-
# Server Configuration
96-
HOST="0.0.0.0"
97-
PORT="8080"
98-
```
196+
**Required Variables**:
197+
- `DATABASE_URL`: PostgreSQL connection string
198+
- `JWT_SECRET`: Secret key for JWT token signing (minimum 6 characters)
199+
- `PORT`: Backend server port (default: 4000)
99200

100-
### 4. Install Dependencies
201+
**Optional Variables**:
202+
- `CORS_ORIGINS`: Comma-separated list of allowed origins (default: `http://localhost:5173`)
203+
- `GEMINI_API_KEY`: API key for Google Gemini (required for Budget Bot features)
101204

102-
Install the dependencies for both the backend and frontend.
205+
#### 4. Install Dependencies
103206

104-
- **Backend**:
105-
```sh
106-
cd apps/backend
107-
npm install
108-
```
207+
Install dependencies for both packages:
109208

110-
- **Frontend**:
111-
```sh
112-
cd ../frontend
113-
npm install
114-
```
209+
```sh
210+
# Backend
211+
cd apps/backend
212+
npm install
213+
214+
# Frontend
215+
cd ../frontend
216+
npm install
217+
```
115218

116219
## 🏃‍♂️ Running the Application
117220

118-
You need to run both the backend and frontend servers simultaneously in separate terminal windows.
221+
### Using the Deployment Script
119222

120-
- **Run the Backend Server**:
121-
```sh
122-
# From the apps/backend directory
123-
npm run dev
124-
```
125-
The backend server will start on the port specified in your `.env` file (default: `8080`).
223+
The deployment script automatically starts both servers. Simply run:
224+
```powershell
225+
.\deploy-eventstack.ps1
226+
```
227+
228+
### Manual Execution
126229

127-
- **Run the Frontend Application**:
128-
```sh
129-
# From the apps/frontend directory
130-
npm run dev
131-
```
132-
The React development server will start, typically on `http://localhost:5173`.
230+
Run both servers in separate terminal windows:
231+
232+
**Backend Server**:
233+
```sh
234+
cd apps/backend
235+
npm run dev
236+
```
237+
The backend will start on `http://localhost:4000` (or the port specified in `.env`).
238+
239+
**Frontend Application**:
240+
```sh
241+
cd apps/frontend
242+
npm run dev
243+
```
244+
The frontend will start on `http://localhost:5173`.
133245

134246
## 🧪 Running Tests
135247

136-
Both packages are equipped with a full suite of unit and integration tests using Vitest.
248+
Both packages are equipped with a comprehensive suite of unit and integration tests using Vitest.
137249

138-
To run the tests for a specific package, navigate to its directory and use the following scripts:
250+
### Test Scripts
139251

140-
- `npm test`: Run all tests once.
141-
- `npm run test:watch`: Run tests in watch mode.
142-
- `npm run testu`: Run unit tests and generate a coverage report.
143-
- `npm run testi`: Run integration tests and generate a coverage report.
144-
- `npm run test:coverage`: Run all tests and generate a combined coverage report.
145-
- `npm run test:report`: Generate PDF reports from the coverage results for both unit and integration tests.
252+
Navigate to the package directory (`apps/backend` or `apps/frontend`) and use the following scripts:
146253

147-
**Example: Running backend tests**
254+
- `npm test`: Run all tests once
255+
- `npm run test:watch`: Run tests in watch mode
256+
- `npm run testu`: Run unit tests and generate a coverage report
257+
- `npm run testi`: Run integration tests and generate a coverage report
258+
- `npm run test:coverage`: Run all tests and generate a combined coverage report
259+
- `npm run test:report`: Generate PDF reports from coverage results for both unit and integration tests
260+
261+
### Examples
262+
263+
**Backend Tests**:
148264
```sh
149265
cd apps/backend
150-
npm test
266+
npm test # Run all tests
267+
npm run testu # Unit tests with coverage
268+
npm run testi # Integration tests with coverage
269+
npm run test:report # Generate PDF coverage reports
270+
```
271+
272+
**Frontend Tests**:
273+
```sh
274+
cd apps/frontend
275+
npm test # Run all tests
276+
npm run testu # Unit tests with coverage
277+
npm run testi # Integration tests with coverage
151278
```
152279

280+
Coverage reports are generated in the `coverage/` directory, and PDF reports are available in `tests/reports/` for each package.
281+

‎User Manual EventStack.pdf‎

409 KB
Binary file not shown.

0 commit comments

Comments
 (0)