Redmine-Gitea-Sync/QUICKSTART.md

# 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.