Goa-gel-fullstack/Documentation/GETTING_STARTED.md

# 🚀 Getting Started - Goa-GEL Documentation Service

Quick start guide to get the documentation service running in under 5 minutes.

---

## ⚡ Quick Start (Choose One Method)

### Method 1: Docker (Recommended) - 2 Minutes

```bash
# 1. Navigate to Documentation directory
cd Documentation

# 2. Build the Docker image
docker build -t goa-gel-docs .

# 3. Run the container
docker run -d -p 8080:80 --name goa-gel-docs goa-gel-docs

# 4. Open in browser
open http://localhost:8080
```

**Done!** The documentation is now running at http://localhost:8080

---

### Method 2: Docker Compose - 1 Minute

```bash
# 1. Navigate to Documentation directory
cd Documentation

# 2. Start the service
docker-compose up -d

# 3. Open in browser
open http://localhost:8080
```

**Done!** The documentation is now running at http://localhost:8080

---

### Method 3: Local Development - 3 Minutes

```bash
# 1. Navigate to Documentation directory
cd Documentation

# 2. Install dependencies
npm install

# 3. Start local server
npm start

# 4. Open in browser
open http://localhost:8080
```

**Done!** The documentation is now running at http://localhost:8080

---

## 📖 What You'll See

### Homepage (http://localhost:8080)

A beautiful landing page with:
- 📊 Platform statistics
- 🎯 Quick start cards for different user roles
- 📚 Complete documentation library
- 👤 Role-based navigation
- ✨ Feature highlights

### Documentation Viewer (http://localhost:8080/viewer.html?doc=USER_GUIDE)

An interactive documentation viewer with:
- 📘 Markdown rendering with syntax highlighting
- 📑 Table of contents (auto-generated)
- 🔍 Quick document selector
- 💾 Download as Markdown
- 🖨️ Print-friendly version
- 📱 Mobile responsive design

---

## 📚 Available Documentation

Navigate to any of these guides:

| Guide | URL | Size |
|-------|-----|------|
| **User Guide** | `/viewer.html?doc=USER_GUIDE` | 650+ lines |
| **Testing Guide** | `/viewer.html?doc=E2E_TESTING_GUIDE` | 600+ lines |
| **Implementation Status** | `/viewer.html?doc=IMPLEMENTATION_COMPLETE` | 380+ lines |
| **Architecture Guide** | `/viewer.html?doc=ARCHITECTURE_GUIDE` | 1000+ lines |
| **Quick Start** | `/viewer.html?doc=QUICK_START` | 200+ lines |
| **Documentation Index** | `/viewer.html?doc=DOCUMENTATION_INDEX` | 400+ lines |
| **Implementation Summary** | `/viewer.html?doc=IMPLEMENTATION_SUMMARY` | 300+ lines |

---

## 🎯 Next Steps

### For Users
1. Click on **"I'm a User"** card on homepage
2. Read your role-specific guide (Admin/Department/Citizen)
3. Follow step-by-step instructions

### For Testers
1. Click on **"I Need to Test"** card
2. Read the E2E Testing Guide
3. Follow the 20 test scenarios

### For Developers
1. Click on **"I'm a Developer"** card
2. Read Implementation Complete guide
3. Review Architecture Guide

### For Architects
1. Click on **"I'm an Architect"** card
2. Read Architecture Guide
3. View system diagrams

---

## 🛠️ Common Commands

### Docker Commands

```bash
# View logs
docker logs -f goa-gel-docs

# Stop the service
docker stop goa-gel-docs

# Start the service
docker start goa-gel-docs

# Restart the service
docker restart goa-gel-docs

# Remove the container
docker stop goa-gel-docs
docker rm goa-gel-docs

# Rebuild after changes
docker build -t goa-gel-docs .
docker stop goa-gel-docs && docker rm goa-gel-docs
docker run -d -p 8080:80 --name goa-gel-docs goa-gel-docs
```

### Docker Compose Commands

```bash
# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose stop

# Restart services
docker-compose restart

# Remove everything
docker-compose down

# Rebuild and restart
docker-compose up -d --build
```

### Local Development Commands

```bash
# Start server (port 8080)
npm start

# Start server with auto-open browser
npm run dev

# Install dependencies
npm install
```

---

## ✅ Verify Installation

### 1. Check Service is Running

```bash
# Test homepage
curl -I http://localhost:8080/

# Expected output:
# HTTP/1.1 200 OK
# Content-Type: text/html
```

### 2. Check Documentation Loads

```bash
# Test documentation file
curl http://localhost:8080/docs/USER_GUIDE.md

# Should return markdown content
```

### 3. Check in Browser

1. Open: http://localhost:8080
2. Should see beautiful homepage
3. Click any card or navigation link
4. Documentation should load

---

## 🐛 Troubleshooting

### Port 8080 Already in Use

**Solution 1: Use Different Port**
```bash
# Docker
docker run -d -p 9090:80 --name goa-gel-docs goa-gel-docs

# Then access at: http://localhost:9090
```

**Solution 2: Find and Kill Process**
```bash
# Find what's using port 8080
lsof -i :8080

# Kill the process (replace PID with actual PID)
kill -9 PID
```

### Docker Build Fails

**Check Docker is Running**
```bash
docker --version
docker ps

# If not running, start Docker Desktop
```

**Clear Docker Cache**
```bash
docker system prune -a
docker build --no-cache -t goa-gel-docs .
```

### Documentation Not Loading

**Check files exist**
```bash
ls -la docs/
# Should see all .md files

ls -la public/
# Should see index.html, viewer.html, css/, js/
```

**Check container logs**
```bash
docker logs goa-gel-docs
# Look for any error messages
```

### Blank Page or 404 Errors

**Clear Browser Cache**
- Press Ctrl+Shift+R (Windows/Linux)
- Press Cmd+Shift+R (Mac)
- Or use Incognito/Private mode

**Check network tab**
- Open browser DevTools (F12)
- Go to Network tab
- Refresh page
- Look for failed requests (red)

---

## 📱 Access from Mobile

### Same Network

1. Find your computer's IP address:
   ```bash
   # Mac/Linux
   ifconfig | grep "inet "

   # Windows
   ipconfig
   ```

2. On mobile, open browser and go to:
   ```
   http://YOUR_IP_ADDRESS:8080
   ```

### Public Access (Advanced)

Use a reverse proxy or cloud hosting (see DEPLOY.md for details)

---

## 🔄 Updating Documentation

### Update Markdown Files

1. Edit `.md` files in `docs/` directory
2. Rebuild and restart:

**Docker:**
```bash
docker build -t goa-gel-docs .
docker stop goa-gel-docs && docker rm goa-gel-docs
docker run -d -p 8080:80 --name goa-gel-docs goa-gel-docs
```

**Local:**
```bash
# No rebuild needed - just refresh browser
# Server automatically serves updated files
```

### Add New Documentation

1. Add new `.md` file to `docs/` directory
2. Update `public/js/viewer.js` - add to `DOC_MAP`:
   ```javascript
   const DOC_MAP = {
       'YOUR_NEW_DOC': '/docs/YOUR_NEW_DOC.md',
       // ... existing entries
   };
   ```
3. Rebuild and restart (if using Docker)

---

## 💡 Tips & Best Practices

### Performance

- Documentation loads instantly (< 1s)
- Syntax highlighting is automatic
- Gzip compression enabled
- Browser caching configured

### Navigation

- Use sidebar for quick navigation
- Use dropdown selector for document switching
- Use table of contents for long documents
- Browser back/forward buttons work

### Viewing

- Click any heading in TOC to jump to section
- Use print button for PDF generation
- Use download button to save Markdown
- Mobile-friendly design works on all devices

---

## 📞 Need Help?

### Documentation

- **README.md**: Complete feature documentation
- **DEPLOY.md**: Production deployment guide
- **This file**: Quick start guide

### Support

- **Email**: support@goa.gov.in
- **Issues**: GitHub repository
- **Documentation**: Available in the service itself

---

## 🎉 Success!

You now have a fully functional documentation service running!

**What's Next?**

1. ✅ Explore the homepage
2. ✅ Read the user guide for your role
3. ✅ Test the documentation viewer features
4. ✅ Share the URL with your team
5. ✅ Deploy to production (see DEPLOY.md)

---

**Happy documenting! 📚**

---

**Version**: 1.0.0
**Last Updated**: February 2026
**Service Port**: 8080 (default)
**Status**: Production Ready ✅