Add QUICKSTART.md
Signed-off-by: Thomas Scott <tombomb122@noreply.localhost>
This commit is contained in:
parent
c86d27d59e
commit
d3474ad48d
|
|
@ -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.
|
||||
Loading…
Reference in New Issue