Skip to content

Commit 03520f5

Browse files
CopilotGeekTrainer
Copilot
and
GeekTrainer
committed
Add comprehensive local setup documentation
Co-authored-by: GeekTrainer <[email protected]>
1 parent 2cf116a commit 03520f5

File tree

2 files changed

+284
-3
lines changed

2 files changed

+284
-3
lines changed

‎LOCAL_SETUP.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# Local Development Setup Guide
2+
3+
This guide will help you set up and run the Tailspin Toys crowdfunding platform on your local machine without using GitHub Codespaces.
4+
5+
## Prerequisites
6+
7+
Before you begin, ensure you have the following installed on your local machine:
8+
9+
### Required Software
10+
11+
1. **Python 3.12 or higher**
12+
- **Windows**: Download from [python.org](https://www.python.org/downloads/)
13+
- **macOS**: Install via [Homebrew](https://brew.sh/): `brew install [email protected]`
14+
- **Linux**: Install via your package manager:
15+
```bash
16+
# Ubuntu/Debian
17+
sudo apt update
18+
sudo apt install python3.12 python3.12-venv python3-pip
19+
20+
# Fedora
21+
sudo dnf install python3.12
22+
```
23+
24+
2. **Node.js 18.x or higher** (includes npm)
25+
- Download from [nodejs.org](https://nodejs.org/) (LTS version recommended)
26+
- Or use [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm):
27+
```bash
28+
nvm install --lts
29+
nvm use --lts
30+
```
31+
32+
3. **Git**
33+
- **Windows**: Download from [git-scm.com](https://git-scm.com/download/win)
34+
- **macOS**: Install via Homebrew: `brew install git` or use Xcode Command Line Tools
35+
- **Linux**: Install via your package manager: `sudo apt install git` (Ubuntu/Debian)
36+
37+
### Verify Installation
38+
39+
Run these commands to verify your installations:
40+
41+
```bash
42+
python3 --version # Should show 3.12 or higher
43+
node --version # Should show v18.x or higher
44+
npm --version # Should show 9.x or higher
45+
git --version # Should show 2.x or higher
46+
```
47+
48+
## Getting Started
49+
50+
### 1. Clone the Repository
51+
52+
If you're working with the original template:
53+
54+
```bash
55+
git clone https://github.com/github-samples/agents-in-sdlc.git
56+
cd agents-in-sdlc
57+
```
58+
59+
Or if you've already created your own copy from the template:
60+
61+
```bash
62+
git clone https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.git
63+
cd YOUR-REPO-NAME
64+
```
65+
66+
### 2. Set Up the Development Environment
67+
68+
The repository includes a setup script that will:
69+
- Create a Python virtual environment
70+
- Install Python dependencies
71+
- Install Node.js dependencies
72+
- Install Playwright browsers for testing
73+
74+
Run the setup script:
75+
76+
```bash
77+
# On macOS/Linux
78+
./scripts/setup-env.sh
79+
80+
# On Windows (using Git Bash or WSL)
81+
bash ./scripts/setup-env.sh
82+
```
83+
84+
> **Note**: The setup script may take several minutes to complete as it downloads and installs all dependencies.
85+
86+
### 3. Start the Application
87+
88+
Once the setup is complete, you can start both the backend API server and the frontend development server:
89+
90+
```bash
91+
./scripts/start-app.sh
92+
```
93+
94+
The script will:
95+
- Start the Flask backend API server on `http://localhost:5100`
96+
- Start the Astro frontend development server on `http://localhost:4321`
97+
98+
You should see output similar to:
99+
100+
```
101+
Starting API (Flask) server...
102+
Starting client (Astro)...
103+
104+
Server (Flask) running at: http://localhost:5100
105+
Client (Astro) server running at: http://localhost:4321
106+
```
107+
108+
### 4. Access the Application
109+
110+
Open your web browser and navigate to:
111+
112+
```
113+
http://localhost:4321
114+
```
115+
116+
You should see the Tailspin Toys crowdfunding platform homepage!
117+
118+
### 5. Stop the Application
119+
120+
To stop both servers, press `Ctrl+C` in the terminal where the application is running.
121+
122+
## Running Tests
123+
124+
### Backend (Python) Tests
125+
126+
To run the Flask API tests:
127+
128+
```bash
129+
./scripts/run-server-tests.sh
130+
```
131+
132+
This script will:
133+
- Set up the Python environment (if not already set up)
134+
- Run all Python unit tests using unittest
135+
136+
### Frontend (End-to-End) Tests
137+
138+
To run the Playwright end-to-end tests:
139+
140+
```bash
141+
cd client
142+
npm run test:e2e
143+
```
144+
145+
> **Note**: Make sure both the backend and frontend servers are running before executing end-to-end tests.
146+
147+
## Project Structure
148+
149+
```
150+
agents-in-sdlc/
151+
├── client/ # Astro/Svelte frontend
152+
│ ├── src/
153+
│ │ ├── components/ # Svelte components
154+
│ │ ├── layouts/ # Astro layout templates
155+
│ │ ├── pages/ # Astro page routes
156+
│ │ └── styles/ # CSS and Tailwind configuration
157+
│ ├── e2e-tests/ # Playwright end-to-end tests
158+
│ └── package.json # Node.js dependencies
159+
├── server/ # Flask backend
160+
│ ├── models/ # SQLAlchemy ORM models
161+
│ ├── routes/ # API endpoints
162+
│ ├── tests/ # Python unit tests
163+
│ ├── utils/ # Utility functions
164+
│ ├── app.py # Flask application entry point
165+
│ └── requirements.txt # Python dependencies
166+
├── scripts/ # Development scripts
167+
│ ├── setup-env.sh # Environment setup
168+
│ ├── start-app.sh # Start both servers
169+
│ └── run-server-tests.sh # Run Python tests
170+
├── data/ # SQLite database files
171+
└── docs/ # Workshop documentation
172+
```
173+
174+
## Development Workflow
175+
176+
### Making Code Changes
177+
178+
1. **Backend Changes**: Edit files in the `server/` directory
179+
- The Flask server runs in debug mode and will auto-reload on changes
180+
181+
2. **Frontend Changes**: Edit files in the `client/src/` directory
182+
- The Astro dev server supports hot module replacement (HMR)
183+
- Changes will automatically refresh in your browser
184+
185+
### Database
186+
187+
The application uses SQLite for the database, which is stored in the `data/` directory. The database is automatically created when you first run the application.
188+
189+
## Troubleshooting
190+
191+
### Port Already in Use
192+
193+
If you see an error about ports 4321 or 5100 already being in use:
194+
195+
1. Find and stop the process using the port:
196+
```bash
197+
# On macOS/Linux
198+
lsof -ti:4321 | xargs kill -9
199+
lsof -ti:5100 | xargs kill -9
200+
201+
# On Windows
202+
netstat -ano | findstr :4321
203+
netstat -ano | findstr :5100
204+
taskkill /PID <PID> /F
205+
```
206+
207+
2. Or change the port in the respective configuration files
208+
209+
### Python Virtual Environment Issues
210+
211+
If you encounter issues with the Python virtual environment:
212+
213+
1. Delete the `venv` directory:
214+
```bash
215+
rm -rf venv
216+
```
217+
218+
2. Re-run the setup script:
219+
```bash
220+
./scripts/setup-env.sh
221+
```
222+
223+
### Node Modules Issues
224+
225+
If you encounter issues with Node.js dependencies:
226+
227+
1. Delete the `node_modules` directory and `package-lock.json`:
228+
```bash
229+
cd client
230+
rm -rf node_modules package-lock.json
231+
```
232+
233+
2. Reinstall dependencies:
234+
```bash
235+
npm install
236+
```
237+
238+
### Permission Denied on Scripts
239+
240+
If you get a "permission denied" error when running scripts:
241+
242+
```bash
243+
chmod +x scripts/*.sh
244+
```
245+
246+
### Playwright Browser Installation
247+
248+
If Playwright browsers are not installed correctly:
249+
250+
```bash
251+
cd client
252+
npx playwright install
253+
```
254+
255+
## Additional Resources
256+
257+
- **Flask Documentation**: https://flask.palletsprojects.com/
258+
- **SQLAlchemy Documentation**: https://www.sqlalchemy.org/
259+
- **Astro Documentation**: https://docs.astro.build/
260+
- **Svelte Documentation**: https://svelte.dev/
261+
- **Tailwind CSS Documentation**: https://tailwindcss.com/
262+
263+
## Workshop Documentation
264+
265+
If you're following the workshop, please refer to the [workshop documentation](./docs/README.md) for guided exercises on using GitHub Copilot and related features.
266+
267+
## Getting Help
268+
269+
If you encounter any issues not covered in this guide:
270+
271+
1. Check the [GitHub Issues](../../issues) for similar problems
272+
2. Review the workshop documentation in the `docs/` directory
273+
3. Open a new issue with details about your environment and the error message
274+
275+
## License
276+
277+
This project is licensed under the terms of the MIT open source license. Please refer to [LICENSE](./LICENSE) for the full terms.

‎README.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,15 @@ This repository contains the project for a 1 hour guided workshop to explore Git
66

77
**To begin the workshop, start at [docs/README.md](./docs/README.md)**
88

9-
Or, if just want to run the app...
9+
The workshop is designed to be completed using [GitHub Codespaces](https://github.com/features/codespaces), which provides a pre-configured cloud development environment.
1010

11-
## Launch the site
11+
## Run locally
1212

13-
A script file has been created to launch the site. You can run it by:
13+
If you prefer to run the application on your local machine instead of using Codespaces, see the [Local Setup Guide](./LOCAL_SETUP.md) for detailed instructions on setting up your local development environment.
14+
15+
## Quick start (local)
16+
17+
If you already have Python 3.12+ and Node.js installed:
1418

1519
```bash
1620
./scripts/start-app.sh

0 commit comments

Comments
 (0)