diff --git a/QUICKSTART.md b/QUICKSTART.md
new file mode 100644
index 0000000..f301d35
--- /dev/null
+++ b/QUICKSTART.md
@@ -0,0 +1,426 @@
+# Quick Start Guide
+
+Get your Redmine-Gitea sync server running in 5 minutes.
+
+## 1. Install Prerequisites
+
+```bash
+# Install Node.js 18+ and npm
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Verify installation
+node --version  # Should be 18.x or higher
+npm --version   # Should be 9.x or higher
+
+# Install PM2 globally
+sudo npm install -g pm2
+
+# Verify PM2 installation
+pm2 --version
+```
+
+## 2. Clone and Setup
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd redmine-gitea-sync
+
+# Install dependencies
+npm install
+```
+
+## 3. Configure Environment
+
+```bash
+# Edit PM2 configuration file
+nano ecosystem.config.cjs
+```
+
+**Update the `env` section with your credentials:**
+
+```javascript
+env: {
+  NODE_ENV: 'production',
+  PORT: 3002,
+  
+  // Redmine
+  REDMINE_API_URL: 'https://your-redmine-instance.com',
+  REDMINE_API_KEY: 'your_api_key_here',
+  
+  // Gitea
+  GITEA_API_URL: 'https://your-gitea-instance.com',
+  GITEA_TOKEN: 'your_token_here',
+  GITEA_OWNER: 'your_username',
+  
+  // Optional: Project mapping
+  PROJECT_MAPPING: '{"YourRepo":"your-project"}',
+}
+```
+
+### Get Your API Keys
+
+**Redmine API Key:**
+1. Log into Redmine
+2. Go to: My Account → API access key
+3. Click "Show" or "Reset" to view your key
+4. Copy the key to `REDMINE_API_KEY`
+
+**Gitea Token:**
+1. Log into Gitea
+2. Go to: Settings → Applications
+3. Generate New Token with these permissions:
+   - `repo` (Full control of repositories)
+   - `write:issue` (Write issues)
+4. Copy the token to `GITEA_TOKEN`
+
+## 4. Start the Server
+
+```bash
+# Start with PM2
+pm2 start ecosystem.config.cjs
+
+# Save PM2 process list
+pm2 save
+
+# Setup auto-start on system boot
+pm2 startup
+# Follow the command it outputs, then:
+pm2 save
+```
+
+You should see:
+
+```
+[PM2] Starting /path/to/server.js in fork_mode (1 instance)
+[PM2] Done.
+┌─────┬──────────────────────────┬─────────┬─────────┬──────────┐
+│ id  │ name                     │ mode    │ status  │ cpu      │
+├─────┼──────────────────────────┼─────────┼─────────┼──────────┤
+│ 0   │ redmine-gitea-sync       │ fork    │ online  │ 0%       │
+└─────┴──────────────────────────┴─────────┴─────────┴──────────┘
+```
+
+View logs in real-time:
+```bash
+pm2 logs redmine-gitea-sync
+```
+
+You should see log output like:
+
+```
+[2025-12-17T01:49:47.000Z] [INFO] Redmine-Gitea Sync Server started on port 3002
+[2025-12-17T01:49:47.000Z] [INFO] Redmine: https://your-redmine.com
+[2025-12-17T01:49:47.000Z] [INFO] Gitea: https://your-gitea.com (owner: your_username)
+```
+
+### Alternative: Development Mode
+
+For testing with auto-reload:
+```bash
+# Stop PM2 version first
+pm2 stop redmine-gitea-sync
+
+# Run in development mode
+npm run dev
+```
+
+## 5. Test the Server
+
+```bash
+# Health check
+curl http://localhost:3002/health
+
+# Status check (tests connections)
+curl http://localhost:3002/status
+```
+
+Expected response:
+
+```json
+{
+  "status": "ok",
+  "uptime": 5.234,
+  "connections": {
+    "redmine": "connected",
+    "gitea": "connected"
+  }
+}
+```
+
+## 6. Configure Webhooks
+
+### Redmine Webhook
+
+1. **Admin access required**
+2. Navigate to: **Administration → Settings → Repositories**
+3. Add webhook:
+   - **URL**: `http://your-server-ip:3002/webhook/redmine`
+   - **Events**: Issues created, Issues updated
+4. Save
+
+**Note:** Replace `your-server-ip` with your actual server IP or domain.
+
+### Gitea Webhook
+
+1. Go to your repository
+2. Navigate to: **Settings → Webhooks**
+3. Add webhook:
+   - **Target URL**: `http://your-server-ip:3002/webhook/gitea`
+   - **HTTP Method**: POST
+   - **POST Content Type**: application/json
+   - **Trigger On**: Issues, Issue Comment
+   - **Active**: ✓ Checked
+4. Add Webhook
+
+## 7. Test the Sync
+
+### Create a Test Issue in Redmine
+
+1. Create a new issue in Redmine
+2. Wait 2-3 seconds
+3. Check your Gitea repository - you should see a new issue
+
+### Create a Test Issue in Gitea
+
+1. Create a new issue in Gitea
+2. Wait 2-3 seconds
+3. Check your Redmine project - you should see a new issue
+
+### Add a Comment
+
+1. Add a comment to either issue
+2. Wait 2-3 seconds
+3. Check the other platform - the comment should appear
+
+## 8. Verify Logs
+
+```bash
+# View real-time logs
+pm2 logs redmine-gitea-sync
+
+# View last 100 lines
+pm2 logs redmine-gitea-sync --lines 100
+
+# View only errors
+pm2 logs redmine-gitea-sync --err
+
+# Monitor all PM2 processes
+pm2 monit
+```
+
+You should see output like:
+
+```
+[INFO] Processing Redmine issue #31: Test Issue
+[INFO] Creating new Gitea issue for Redmine #31
+[INFO] Successfully synced Redmine issue #31 to Gitea issue #27
+```
+
+### PM2 Commands Quick Reference
+
+```bash
+# View status of all processes
+pm2 list
+
+# Restart the server
+pm2 restart redmine-gitea-sync
+
+# Stop the server
+pm2 stop redmine-gitea-sync
+
+# Delete from PM2
+pm2 delete redmine-gitea-sync
+
+# View detailed info
+pm2 show redmine-gitea-sync
+```
+
+## Common Issues
+
+### Issue: "Cannot connect to Redmine"
+
+**Solution:**
+- Verify `REDMINE_API_URL` is correct (no trailing slash)
+- Test API key: `curl -H "X-Redmine-API-Key: YOUR_KEY" https://your-redmine.com/issues.json`
+- Check firewall rules
+
+### Issue: "Cannot connect to Gitea"
+
+**Solution:**
+- Verify `GITEA_API_URL` is correct (no trailing slash)
+- Test token: `curl -H "Authorization: token YOUR_TOKEN" https://your-gitea.com/api/v1/user`
+- Check token has correct permissions
+
+### Issue: "Request failed with status code 422"
+
+**Solutions:**
+- Update to latest version: `git pull && pm2 restart redmine-gitea-sync`
+- Enable debug logging to see validation details
+- See [FIX_SUMMARY.md](FIX_SUMMARY.md) for recent fixes
+
+### Issue: "Webhook not triggering"
+
+**Solution:**
+- Verify webhook URL is accessible from Redmine/Gitea servers
+- Check firewall allows incoming connections on port 3002
+- Test manually: `curl -X POST http://localhost:3002/health`
+
+### Issue: "Project not found"
+
+**Solution:**
+- Check project mapping in `ecosystem.config.cjs`
+- Verify repository exists in Gitea
+- Verify project exists in Redmine
+- Project identifiers must match (case-sensitive)
+
+### Issue: "Comments not syncing from Redmine"
+
+**Solutions:**
+- Ensure Redmine webhook includes "Issues updated" events
+- Verify notes have actual text content (not just field changes)
+- Clear cache: `curl -X POST http://localhost:3002/cache/clear`
+- See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#comments-not-syncing-from-redmine-to-gitea)
+
+### Issue: "Labels not mapping to Redmine tracker/priority"
+
+**Solutions:**
+- Ensure label names match exactly: "bug", "feature", "High Priority"
+- Update to latest version with label mapping fixes
+- See [FIX_SUMMARY.md](FIX_SUMMARY.md#fix-1-label-to-field-mapping)
+
+**For detailed troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)**
+
+## Project Mapping
+
+If your Gitea repository name doesn't match your Redmine project identifier, configure mapping in `ecosystem.config.cjs`:
+
+```javascript
+env: {
+  // ... other config
+  PROJECT_MAPPING: '{"GiteaRepoName":"redmine-project-id"}',
+}
+```
+
+Example:
+
+```javascript
+PROJECT_MAPPING: '{"AI_Smuggling":"ai-smuggling","MyApp":"my-application"}',
+```
+
+After updating, restart PM2:
+```bash
+pm2 restart redmine-gitea-sync --update-env
+```
+
+### Alternative: Using .env file
+
+You can also use a `.env` file:
+
+```env
+PROJECT_MAPPING={"GiteaRepoName":"redmine-project-id"}
+```
+
+Then start without PM2:
+```bash
+npm start
+```
+
+## Next Steps
+
+- **PM2 Management**: See [PM2_GUIDE.md](PM2_GUIDE.md) for complete PM2 reference
+- **Production Deployment**: See [DEPLOYMENT.md](DEPLOYMENT.md)
+- **Full Documentation**: See [README.md](README.md)
+- **API Details**: See [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
+
+## Features Overview
+
+What gets synced:
+
+- ✓ Issue titles and descriptions
+- ✓ Issue status (open/closed)
+- ✓ Comments and journals
+- ✓ Assignees
+- ✓ Due dates
+- ✓ Labels (from trackers, priorities, categories)
+- ✓ Milestones (from Redmine versions)
+- ✓ Estimated hours
+
+What doesn't get synced (yet):
+
+- ✗ Attachments
+- ✗ Watchers
+- ✗ Related issues
+- ✗ Time entries
+
+## Customization
+
+### Disable Features
+
+Edit `ecosystem.config.cjs`:
+
+```javascript
+env: {
+  // ... other config
+  
+  // Disable label sync
+  SYNC_LABELS: 'false',
+  
+  // Disable milestone sync
+  SYNC_MILESTONES: 'false',
+  
+  // Disable custom fields
+  SYNC_CUSTOM_FIELDS: 'false',
+}
+```
+
+Restart PM2:
+```bash
+pm2 restart redmine-gitea-sync --update-env
+```
+
+### Adjust Cache TTL
+
+```javascript
+env: {
+  // Increase cache time (milliseconds)
+  CACHE_TTL: '60000',  // 60 seconds
+}
+```
+
+### Change Log Level
+
+```javascript
+env: {
+  // Show debug information
+  LOG_LEVEL: 'debug',
+  LOG_VERBOSE: 'true',
+}
+```
+
+Or use development mode:
+```bash
+pm2 start ecosystem.config.cjs --env development
+```
+
+## Support
+
+Need help?
+
+1. Check the [README.md](README.md) for detailed documentation
+2. Review [API_DOCUMENTATION.md](API_DOCUMENTATION.md) for API details
+3. See [DEPLOYMENT.md](DEPLOYMENT.md) for production setup
+4. Open an issue in the repository
+
+## Security Note
+
+For production use:
+
+1. Use HTTPS for webhook URLs
+2. Secure your `.env` file: `chmod 600 .env`
+3. Consider IP whitelisting
+4. Implement webhook signature verification
+5. Use a reverse proxy (Nginx/Apache)
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for production security best practices.
\ No newline at end of file