mirror of
https://github.com/StarFleetCPTN/GoMFT.git
synced 2026-09-14 02:20:45 +02:00
feat: Integrate Docusaurus for documentation and enhance project structure
- Added Docusaurus configuration and initial setup for documentation. - Created multiple documentation pages covering installation, configuration, and core concepts. - Implemented a GitHub Actions workflow for automatic deployment of documentation to GitHub Pages. - Updated .gitignore to exclude Docusaurus build artifacts and dependencies. - Enhanced README with a link to the online documentation.
This commit is contained in:
StarFleetCPTN
@@ -0,0 +1,183 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Admin Tools
|
||||
---
|
||||
|
||||
# Admin Tools
|
||||
|
||||
GoMFT provides a comprehensive set of administrative tools for system management, monitoring, and maintenance. These tools help administrators maintain the system, troubleshoot issues, and ensure optimal performance.
|
||||
|
||||
## Accessing Admin Tools
|
||||
|
||||
Admin tools are available to users with administrator privileges:
|
||||
|
||||
1. Log in with an administrator account
|
||||
2. Navigate to **Admin Tools** in the sidebar menu
|
||||
|
||||
## Log Viewer
|
||||
|
||||
The Admin Tools panel includes an integrated log viewer with the following features:
|
||||
|
||||
### Features
|
||||
|
||||
- **Log File Browser**: View a list of all available log files in the system
|
||||
- **Real-time Log Viewing**: View log file contents directly in the web interface
|
||||
- **Refresh Function**: Update the log list and content with the latest information
|
||||
- **User-friendly Interface**: Clean, readable presentation with custom scrolling
|
||||
- **Dark Mode Support**: Consistent theming with the rest of the application
|
||||
- **Navigation**: Easily switch between different log files
|
||||
|
||||
### Available Logs
|
||||
|
||||
- **Application Logs**: General application logs
|
||||
- **Transfer Logs**: Detailed logs of file transfer operations
|
||||
- **Authentication Logs**: Login attempts and authentication events
|
||||
- **Scheduler Logs**: Information about scheduled job execution
|
||||
- **API Logs**: API usage and requests
|
||||
- **Webhook Logs**: Records of webhook delivery attempts
|
||||
- **Email Logs**: Email sending attempts and errors
|
||||
|
||||
### Using the Log Viewer
|
||||
|
||||
1. Select a log category from the dropdown menu
|
||||
2. Choose a specific log file from the list
|
||||
3. View the log content in the main panel
|
||||
4. Use the search function to find specific text
|
||||
5. Click **Refresh** to update with the latest entries
|
||||
|
||||
## Database Management
|
||||
|
||||
The Admin Tools interface also includes database management capabilities:
|
||||
|
||||
### Backup Management
|
||||
|
||||
- **Create Backup**: Generate a backup of the GoMFT database
|
||||
- **Schedule Backups**: Configure automatic backup schedules
|
||||
- **View Backups**: List all available backups with their dates and sizes
|
||||
- **Download Backup**: Download a backup file for safekeeping
|
||||
- **Restore Backup**: Restore the system from a previous backup
|
||||
|
||||
### Database Operations
|
||||
|
||||
- **Optimize Database**: Run maintenance tasks to optimize performance
|
||||
- **Check Integrity**: Verify database integrity and identify issues
|
||||
- **Vacuum Database**: Reclaim unused space in the database
|
||||
- **View Statistics**: Get database size and table statistics
|
||||
|
||||
## System Information
|
||||
|
||||
The System Information panel provides a comprehensive overview of your GoMFT installation:
|
||||
|
||||
### System Stats
|
||||
|
||||
- **Version Information**: Current GoMFT version and build details
|
||||
- **System Resources**: CPU, memory, and disk usage
|
||||
- **Uptime**: System uptime and start time
|
||||
- **Active Transfers**: Currently running transfers
|
||||
- **Queued Transfers**: Transfers waiting to be executed
|
||||
- **Database Size**: Current size of the database
|
||||
|
||||
### Health Checks
|
||||
|
||||
- **Service Status**: Status of all system services
|
||||
- **Storage Space**: Available space in data directories
|
||||
- **Connection Tests**: Tests for external services like SMTP
|
||||
- **Rclone Status**: Verify rclone availability and version
|
||||
|
||||
## User Management
|
||||
|
||||
Administrators can manage user accounts and permissions:
|
||||
|
||||
### User Operations
|
||||
|
||||
- **Create User**: Add new users to the system
|
||||
- **Edit User**: Modify existing user details and permissions
|
||||
- **Deactivate User**: Temporarily disable user accounts
|
||||
- **Delete User**: Permanently remove a user account
|
||||
- **Reset Password**: Force password reset for a user
|
||||
|
||||
### Role Management
|
||||
|
||||
- **View Roles**: List all available roles and their permissions
|
||||
- **Create Role**: Define custom roles with specific permissions
|
||||
- **Edit Role**: Modify permissions for existing roles
|
||||
- **Assign Roles**: Change role assignments for users
|
||||
|
||||
## System Settings
|
||||
|
||||
The System Settings section allows customization of various system parameters:
|
||||
|
||||
### General Settings
|
||||
|
||||
- **System Name**: Customize the application name
|
||||
- **Base URL**: Set the base URL for the application
|
||||
- **Time Zone**: Configure the system time zone
|
||||
- **Date Format**: Set the preferred date and time format
|
||||
- **Default Language**: Set the default interface language
|
||||
|
||||
### Security Settings
|
||||
|
||||
- **Password Policy**: Configure password complexity requirements
|
||||
- **Session Timeout**: Set the inactive session timeout period
|
||||
- **Failed Login Limit**: Set thresholds for account lockouts
|
||||
- **API Token Management**: Configure API token policies
|
||||
|
||||
### Email Settings
|
||||
|
||||
- **SMTP Configuration**: Set up the mail server for notifications
|
||||
- **Email Templates**: Customize notification email templates
|
||||
- **Notification Rules**: Configure default notification settings
|
||||
|
||||
### Transfer Settings
|
||||
|
||||
- **Concurrency Limits**: Set maximum simultaneous transfers
|
||||
- **Bandwidth Limits**: Configure default bandwidth limitations
|
||||
- **Temporary Storage**: Configure temp directory for transfers
|
||||
- **Transfer Timeouts**: Set default timeouts for transfers
|
||||
|
||||
## Maintenance Mode
|
||||
|
||||
Administrators can put the system into maintenance mode when needed:
|
||||
|
||||
<!-- ### Maintenance Options
|
||||
|
||||
- **Enable Maintenance Mode**: Temporarily restrict access to admin users
|
||||
- **Scheduled Maintenance**: Schedule maintenance windows
|
||||
- **Maintenance Message**: Customize the message shown to users
|
||||
- **Allow Specific IPs**: Allow specific IP addresses during maintenance -->
|
||||
|
||||
## Import/Export
|
||||
|
||||
The system provides facilities for importing and exporting configuration:
|
||||
|
||||
### Import/Export Features
|
||||
|
||||
- **Export Configurations**: Export transfer configurations as JSON
|
||||
- **Import Configurations**: Import configurations from JSON files
|
||||
- **Migrate Settings**: Move settings between GoMFT instances
|
||||
- **Bulk Operations**: Perform operations on multiple items
|
||||
|
||||
## Audit Logs
|
||||
|
||||
For security and compliance, GoMFT maintains comprehensive audit logs:
|
||||
|
||||
### Audit Log Features
|
||||
|
||||
- **User Actions**: Records of all user-initiated actions
|
||||
- **System Events**: Important system-level events
|
||||
- **Authentication Events**: Login, logout, and access attempts
|
||||
- **Configuration Changes**: Changes to system configuration
|
||||
- **Filtering**: Filter logs by user, action type, and date range
|
||||
- **Export**: Export audit logs for compliance reporting
|
||||
|
||||
<!-- ## Troubleshooting Tools
|
||||
|
||||
The Admin Tools includes several utilities for troubleshooting:
|
||||
|
||||
### Troubleshooting Features
|
||||
|
||||
- **Test Connections**: Verify connectivity to remote systems
|
||||
- **Check File Permissions**: Test access to file systems
|
||||
- **Debug Mode**: Enable additional logging for troubleshooting
|
||||
- **Transfer Simulation**: Test transfers without moving data
|
||||
- **System Check**: Run a comprehensive system check -->
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Gotify Notifications
|
||||
---
|
||||
|
||||
# Gotify Notifications
|
||||
|
||||
Gotify is a simple server for sending and receiving push notifications. GoMFT integrates with Gotify to provide real-time notifications for transfer events and system alerts.
|
||||
|
||||
## Overview
|
||||
|
||||
Gotify integration allows GoMFT to:
|
||||
|
||||
- Send push notifications to your self-hosted Gotify server
|
||||
- Customize notification priority based on event importance
|
||||
- Include detailed transfer information in notifications
|
||||
- Support private and secure notification delivery
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before setting up Gotify notifications in GoMFT, you need:
|
||||
|
||||
1. A running Gotify server (self-hosted)
|
||||
2. An application token from your Gotify server
|
||||
3. Network connectivity between GoMFT and the Gotify server
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Gotify Settings
|
||||
|
||||
To configure Gotify notifications:
|
||||
|
||||
1. Navigate to **Settings** > **Notification Services** > **Add New** > **Gotify**
|
||||
2. Configure the following settings:
|
||||
- **Gotify Server URL**: The URL of your Gotify server (e.g., `https://gotify.example.com`)
|
||||
- **Application Token**: The token for your GoMFT application in Gotify
|
||||
- **Default Priority**: The default priority level for notifications (1-10)
|
||||
- **Verify SSL**: Whether to verify SSL certificates (recommended for production)
|
||||
|
||||
### Testing Gotify Connection
|
||||
|
||||
After configuring your Gotify settings:
|
||||
|
||||
1. Click **Test Connection** to verify connectivity with your Gotify server
|
||||
2. Click **Send Test Notification** to send a test message
|
||||
|
||||
## Notification Content
|
||||
|
||||
### Priority Levels
|
||||
|
||||
Gotify uses numeric priority levels that GoMFT leverages for different event types:
|
||||
|
||||
| Priority | Usage in GoMFT |
|
||||
|----------|----------------|
|
||||
| 1-3 | Low priority: successful transfers, routine events |
|
||||
| 4-7 | Medium priority: warnings, transfers with issues |
|
||||
| 8-10 | High priority: failed transfers, critical system issues |
|
||||
|
||||
### Example Notifications
|
||||
|
||||
GoMFT sends structured notifications with helpful information:
|
||||
|
||||
#### Successful Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Completed: Daily Backup
|
||||
Message: Successfully transferred 123 files (1.45 GB) in 2:15
|
||||
Priority: 3
|
||||
```
|
||||
|
||||
#### Failed Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Failed: Daily Backup
|
||||
Message: Error: Connection refused to destination server
|
||||
Files processed: 45/123
|
||||
Size transferred: 0.5/1.45 GB
|
||||
Priority: 8
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Connection Refused**: Ensure the Gotify server URL is correct and accessible
|
||||
- **Authentication Failed**: Verify the Application Token is correct
|
||||
- **SSL Certificate Errors**: Check the Verify SSL setting and certificate validity
|
||||
|
||||
### Gotify Logs
|
||||
|
||||
To troubleshoot notification issues:
|
||||
|
||||
1. Check the GoMFT logs: **Admin Tools** > **Logs** > filter for "gotify"
|
||||
2. Review the Gotify server logs for any errors
|
||||
3. Verify network connectivity between GoMFT and the Gotify server
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use HTTPS** for your Gotify server to ensure secure communication
|
||||
- **Set Appropriate Priorities** to differentiate between routine and critical notifications
|
||||
- **Use Client Applications** on your devices to receive Gotify notifications
|
||||
- **Set Up Multiple Notification Methods** for critical events
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Notifications Overview
|
||||
---
|
||||
|
||||
# Notifications Overview
|
||||
|
||||
GoMFT provides a comprehensive notification system to keep you informed about important events in your file transfer workflows. This page provides an overview of the notification system and the different notification types available.
|
||||
|
||||
## Notification System
|
||||
|
||||
The notification system in GoMFT is designed to be:
|
||||
|
||||
- **Flexible**: Choose from multiple notification channels
|
||||
- **Configurable**: Set up different notifications for different events
|
||||
- **Reliable**: Ensure critical events are always reported
|
||||
- **Secure**: Protect sensitive information in notifications
|
||||
|
||||
## Notification Triggers
|
||||
|
||||
Notifications can be triggered by various events in GoMFT:
|
||||
|
||||
### Transfer-Related Events
|
||||
|
||||
- **Transfer Completion**: When a file transfer is successfully completed
|
||||
- **Transfer Failure**: When a file transfer fails for any reason
|
||||
- **Transfer Start**: When a file transfer begins
|
||||
- **Transfer Threshold**: When a transfer exceeds a defined duration threshold
|
||||
|
||||
### Schedule-Related Events
|
||||
|
||||
- **Schedule Execution**: When a scheduled task runs
|
||||
- **Schedule Failure**: When a scheduled task fails to run
|
||||
- **Schedule Creation/Modification**: When schedules are created or modified
|
||||
|
||||
<!-- ### System Events
|
||||
|
||||
- **System Warnings**: Alerts about system resource usage (disk space, memory, etc.)
|
||||
- **Service Status Changes**: When system services change state
|
||||
- **Authentication Events**: Failed login attempts or other security events
|
||||
- **Database Events**: Database backup completion, migration, or issues -->
|
||||
|
||||
## Notification Types
|
||||
|
||||
GoMFT supports multiple notification types to ensure you can receive alerts through your preferred channels:
|
||||
|
||||
|
||||
### Webhook Notifications
|
||||
|
||||
Send HTTP requests to external systems or services when events occur. Features include:
|
||||
- Configurable HTTP methods (POST, PUT, PATCH)
|
||||
- JSON or XML payload formats
|
||||
- Support for authentication
|
||||
- Customizable retry strategy for improved reliability
|
||||
[Learn more about Webhook Notifications](./webhook-notifications)
|
||||
|
||||
### Mobile Push Notifications
|
||||
|
||||
Receive notifications directly on your mobile devices:
|
||||
|
||||
#### Ntfy Notifications
|
||||
- Simple HTTP-based push notifications to phones and desktops
|
||||
- Customizable priority levels and notification tags
|
||||
- Support for self-hosted or cloud-based ntfy servers
|
||||
[Learn more about Ntfy Notifications](./ntfy-notifications)
|
||||
|
||||
#### Pushover Notifications
|
||||
- Real-time push notifications to all your devices
|
||||
- Priority levels for urgent notifications
|
||||
- Custom sounds and delivery options
|
||||
[Learn more about Pushover Notifications](./pushover-notifications)
|
||||
|
||||
#### Pushbullet Notifications
|
||||
- Cross-platform notifications across all your devices
|
||||
- Optional end-to-end encryption
|
||||
- Support for notification mirroring
|
||||
[Learn more about Pushbullet Notifications](./pushbullet-notifications)
|
||||
|
||||
#### Gotify Notifications
|
||||
- Self-hosted push notification service
|
||||
- Customizable priority levels
|
||||
- Private and secure notification delivery
|
||||
[Learn more about Gotify Notifications](./gotify-notifications)
|
||||
|
||||
## Notification Templates
|
||||
|
||||
Each notification type uses customizable templates to format the notification content. Templates support variables that are replaced with actual values when the notification is sent.
|
||||
|
||||
Common template variables include:
|
||||
|
||||
- `{{transfer_name}}`: Name of the transfer
|
||||
- `{{transfer_status}}`: Status of the transfer (success, failure, etc.)
|
||||
- `{{start_time}}`: When the transfer started
|
||||
- `{{end_time}}`: When the transfer completed
|
||||
- `{{duration}}`: How long the transfer took
|
||||
- `{{total_files}}`: Number of files transferred
|
||||
- `{{total_size}}`: Total size of transferred data
|
||||
- `{{error_message}}`: Detailed error information (for failures)
|
||||
|
||||
## Notification Management
|
||||
|
||||
### Configuration
|
||||
|
||||
Notifications are configured at multiple levels:
|
||||
|
||||
1. **Global Level**: Default notification settings for all transfers
|
||||
2. **Transfer Level**: Specific notification settings for individual transfers
|
||||
3. **Schedule Level**: Notification settings for scheduled transfers
|
||||
|
||||
### Notification History
|
||||
|
||||
GoMFT maintains a history of sent notifications, allowing you to:
|
||||
|
||||
- Review past notifications
|
||||
- Verify notification delivery
|
||||
- Resend notifications if needed
|
||||
- Audit notification patterns
|
||||
|
||||
## Getting Started with Notifications
|
||||
|
||||
To start using GoMFT notifications:
|
||||
|
||||
1. Navigate to **Settings** > **Notifications**
|
||||
2. Configure your preferred notification channels
|
||||
3. Test each notification channel
|
||||
4. Apply notifications to specific transfers or schedules
|
||||
|
||||
For specific notification types, refer to the corresponding documentation pages in this section.
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Ntfy Notifications
|
||||
---
|
||||
|
||||
# Ntfy Notifications
|
||||
|
||||
Ntfy is a simple HTTP-based pub-sub notification service that allows you to send push notifications to your phone or desktop. GoMFT seamlessly integrates with Ntfy to deliver notifications about your file transfers and system events.
|
||||
|
||||
## Overview
|
||||
|
||||
Ntfy integration in GoMFT enables:
|
||||
|
||||
- Push notifications to mobile devices and desktops
|
||||
- Choice between public ntfy.sh service or self-hosted Ntfy server
|
||||
- Customizable notification topics, priorities, and tags
|
||||
- Support for notification actions and attachments
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring Ntfy notifications in GoMFT, you should:
|
||||
|
||||
1. Install the Ntfy app on your devices (available for Android, iOS, and desktop)
|
||||
2. Subscribe to your chosen topic in the Ntfy app
|
||||
3. Optionally set up your own Ntfy server for increased privacy
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Ntfy Settings
|
||||
|
||||
To configure Ntfy notifications in GoMFT:
|
||||
|
||||
1. Navigate to **Settings** > **Notification Services** > **Add New** > **Ntfy**
|
||||
2. Configure the following settings:
|
||||
- **Ntfy Server URL**: The URL of the Ntfy server (default: `https://ntfy.sh`)
|
||||
- **Default Topic**: The notification topic your devices are subscribed to
|
||||
- **Default Priority**: Priority level for notifications (1-5)
|
||||
- **Authentication**: Access token or username/password if required
|
||||
- **Default Tags**: Icon tags for different notification types
|
||||
|
||||
### Testing Ntfy Connection
|
||||
|
||||
After configuring your Ntfy settings:
|
||||
|
||||
1. Click **Send Test Notification** to send a test notification to your devices
|
||||
|
||||
## Notification Content
|
||||
|
||||
### Priority Levels
|
||||
|
||||
Ntfy supports five priority levels that GoMFT uses effectively:
|
||||
|
||||
| Priority | Level | Usage in GoMFT |
|
||||
|----------|-------|----------------|
|
||||
| 1 | Min | Background information, debug notifications |
|
||||
| 2 | Low | Successful transfers, routine events |
|
||||
| 3 | Default | Standard notifications, warnings |
|
||||
| 4 | High | Transfer failures, important alerts |
|
||||
| 5 | Max | Critical system issues, emergency alerts |
|
||||
|
||||
### Notification Tags
|
||||
|
||||
GoMFT uses meaningful tags in Ntfy notifications to provide visual cues:
|
||||
|
||||
| Tag | Usage |
|
||||
|-----|-------|
|
||||
| `✅` | Successful transfers |
|
||||
| `❌` | Failed transfers |
|
||||
| `⚠️` | Warnings or transfers with issues |
|
||||
| `🔄` | Transfer in progress |
|
||||
| `🔍` | Monitoring events |
|
||||
| `⚙️` | System events |
|
||||
|
||||
### Example Notifications
|
||||
|
||||
GoMFT sends structured notifications with helpful information:
|
||||
|
||||
#### Successful Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Completed: Daily Backup
|
||||
Message: Successfully transferred 123 files (1.45 GB) in 2:15
|
||||
Priority: 2 (Low)
|
||||
Tags: ✅,📁
|
||||
```
|
||||
|
||||
#### Failed Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Failed: Daily Backup
|
||||
Message: Error: Connection refused to destination server
|
||||
Files processed: 45/123
|
||||
Size transferred: 0.5/1.45 GB
|
||||
Priority: 4 (High)
|
||||
Tags: ❌,📁
|
||||
Click action: Open GoMFT
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Custom Templates
|
||||
|
||||
Customize notification content with templates:
|
||||
|
||||
```
|
||||
Title: {{event_type}}: {{transfer_name}}
|
||||
Message: {{status}} - {{files_transferred}} files ({{total_size}}) in {{duration}}
|
||||
Priority: {% if status == "failed" %}4{% else %}2{% endif %}
|
||||
Tags: {% if status == "success" %}✅{% else %}❌{% endif %},📁
|
||||
```
|
||||
|
||||
## Self-Hosting Ntfy
|
||||
|
||||
For enhanced privacy and control, you can self-host your own Ntfy server:
|
||||
|
||||
1. Follow the [Ntfy self-hosting guide](https://docs.ntfy.sh/install/)
|
||||
2. Update your GoMFT configuration to point to your self-hosted server
|
||||
3. Configure authentication as needed
|
||||
|
||||
Example configuration for self-hosted Ntfy:
|
||||
|
||||
```yaml
|
||||
ntfy:
|
||||
server_url: https://ntfy.example.com
|
||||
default_topic: gomft
|
||||
authentication:
|
||||
type: basic
|
||||
username: ${NTFY_USERNAME}
|
||||
password: ${NTFY_PASSWORD}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Notifications Not Arriving**: Verify you've subscribed to the correct topic
|
||||
- **Authentication Errors**: Check credentials and authentication method
|
||||
- **Connection Issues**: Ensure the Ntfy server is accessible from GoMFT
|
||||
- **App Configuration**: Verify notification settings in your Ntfy app
|
||||
|
||||
### Ntfy Logs
|
||||
|
||||
To troubleshoot notification issues:
|
||||
|
||||
1. Check the GoMFT logs: **Administration** > **Log Viewer** > filter for "ntfy"
|
||||
2. If self-hosting, check your Ntfy server logs
|
||||
3. Verify your device has properly functioning notifications
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use Unique Topics** to prevent unauthorized notifications
|
||||
- **Set Appropriate Priorities** based on event importance
|
||||
- **Consider Self-Hosting** for sensitive environments
|
||||
- **Keep Topic Names Secret** as they act like passwords
|
||||
- **Set Up Multiple Notification Methods** for critical systems
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: Pushbullet Notifications
|
||||
---
|
||||
|
||||
# Pushbullet Notifications
|
||||
|
||||
Pushbullet is a cross-platform notification service that allows you to receive notifications on multiple devices. GoMFT integrates with Pushbullet to deliver timely notifications about your file transfers and system events.
|
||||
|
||||
## Overview
|
||||
|
||||
Pushbullet integration in GoMFT offers:
|
||||
|
||||
- Cross-platform notifications across your devices (Android, iOS, Chrome, Firefox, etc.)
|
||||
- Option to send to all devices or specific devices
|
||||
- Rich notification content with transfer details
|
||||
- Support for notification mirroring between devices
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring Pushbullet notifications in GoMFT, you need:
|
||||
|
||||
1. A Pushbullet account
|
||||
2. Pushbullet API access token
|
||||
3. Pushbullet app installed on your devices
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Pushbullet Settings
|
||||
|
||||
To configure Pushbullet notifications:
|
||||
|
||||
1. Navigate to **Settings** > **Notification Services** > **Add New** > **Pushbullet**
|
||||
2. Configure the following settings:
|
||||
- **API Token**: Your Pushbullet access token
|
||||
- **Default Device**: The device identifier to send notifications to (optional)
|
||||
- **Default Type**: "Note" (default) or "Link"
|
||||
|
||||
### Getting Your Pushbullet API Token
|
||||
|
||||
1. Log in to your Pushbullet account at [pushbullet.com](https://www.pushbullet.com/)
|
||||
2. Go to **Settings** > **Account**
|
||||
3. In the **Access Tokens** section, click **Create Access Token**
|
||||
4. Copy the generated token and paste it into GoMFT
|
||||
|
||||
### Testing Pushbullet Connection
|
||||
|
||||
After configuring your Pushbullet settings:
|
||||
|
||||
1. Click **Send Test Notification** to send a test notification to your devices
|
||||
|
||||
## Notification Content
|
||||
|
||||
### Notification Types
|
||||
|
||||
GoMFT supports two types of Pushbullet notifications:
|
||||
|
||||
#### Note Type
|
||||
|
||||
Simple notifications with a title and body:
|
||||
|
||||
```
|
||||
Title: Transfer Complete: Daily Backup
|
||||
Body: Successfully transferred 123 files (1.45 GB) in 2:15
|
||||
```
|
||||
|
||||
#### Link Type
|
||||
|
||||
Notifications that include a link to the GoMFT interface:
|
||||
|
||||
```
|
||||
Title: Transfer Failed: Daily Backup
|
||||
Body: Error: Connection refused to destination server
|
||||
URL: https://gomft.example.com/transfers/123
|
||||
```
|
||||
|
||||
### Example Notifications
|
||||
|
||||
#### Successful Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Complete: Daily Backup
|
||||
Body: Transfer completed successfully at 2023-09-15 14:22:33
|
||||
Files: 123
|
||||
Size: 1.45 GB
|
||||
Duration: 00:02:15
|
||||
```
|
||||
|
||||
#### Failed Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Failed: Daily Backup
|
||||
Body: Transfer failed with error: Connection refused
|
||||
Files Processed: 45/123
|
||||
Size Transferred: 0.5/1.45 GB
|
||||
Duration: 00:01:05
|
||||
Error: Failed to connect to destination server
|
||||
URL: https://gomft.example.com/transfers/123
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **API Token Errors**: Verify your Pushbullet API token is correct
|
||||
- **No Notifications Arriving**: Check device connectivity and Pushbullet app settings
|
||||
- **Rate Limiting**: Pushbullet has API rate limits; spread out notification frequency
|
||||
- **Device Selection Issues**: Verify device identifiers if targeting specific devices
|
||||
|
||||
### Pushbullet Logs
|
||||
|
||||
To troubleshoot notification issues:
|
||||
|
||||
1. Check the GoMFT logs: **Administration** > **Log Viewer** > filter for "pushbullet"
|
||||
2. Review the Pushbullet account activity in your Pushbullet account
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Secure Your API Token**: Treat your Pushbullet API token as sensitive information
|
||||
- **Group Related Notifications** to avoid notification fatigue
|
||||
- **Include Action Links** for quick access to relevant GoMFT pages
|
||||
- **Set Up Multiple Notification Methods** for critical systems
|
||||
|
||||
## Pushbullet Alternatives
|
||||
|
||||
If you encounter limitations with Pushbullet, GoMFT also supports:
|
||||
|
||||
- [Email Notifications](./email-notifications)
|
||||
- [Gotify](./gotify-notifications)
|
||||
- [Ntfy](./ntfy-notifications)
|
||||
- [Pushover](./pushover-notifications)
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: Pushover Notifications
|
||||
---
|
||||
|
||||
# Pushover Notifications
|
||||
|
||||
Pushover is a simple notification service that makes it easy to send real-time notifications to your Android and iOS devices, as well as desktop computers. GoMFT integrates with Pushover to deliver instant notifications about your file transfers and system events.
|
||||
|
||||
## Overview
|
||||
|
||||
Pushover integration in GoMFT provides:
|
||||
|
||||
- Real-time push notifications to mobile devices and desktops
|
||||
- Prioritized notifications with different sounds and attention levels
|
||||
- Customizable notification content with detailed transfer information
|
||||
- Support for notification grouping by device or application
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring Pushover notifications in GoMFT, you need:
|
||||
|
||||
1. A [Pushover account](https://pushover.net/)
|
||||
2. Your Pushover user key
|
||||
3. A registered Pushover application (API token)
|
||||
4. Pushover app installed on your devices
|
||||
|
||||
## Configuration
|
||||
|
||||
### Registering a GoMFT Application in Pushover
|
||||
|
||||
1. Log in to your Pushover account at [pushover.net](https://pushover.net/)
|
||||
2. Go to [Your Applications](https://pushover.net/apps/build)
|
||||
3. Create a new application:
|
||||
- **Name**: GoMFT
|
||||
- **Type**: Application
|
||||
- **Description**: GoMFT File Transfer Notifications
|
||||
- **URL**: Your GoMFT instance URL (optional)
|
||||
- **Icon**: Upload a custom icon (optional)
|
||||
4. After creation, you'll receive an **API Token/Key** for your application
|
||||
|
||||
### Global Pushover Settings
|
||||
|
||||
To configure Pushover notifications in GoMFT:
|
||||
|
||||
1. Navigate to **Settings** > **Notification Services** > **Add New** > **Pushover**
|
||||
2. Configure the following settings:
|
||||
- **User Key**: Your Pushover user key
|
||||
- **API Token**: Your GoMFT application's API token
|
||||
- **Default Priority**: Default priority level (-2 to 2)
|
||||
- **Default Sound**: Sound for notifications
|
||||
- **Default Device**: Specific device or blank for all devices
|
||||
|
||||
### Testing Pushover Connection
|
||||
|
||||
After configuring your Pushover settings:
|
||||
|
||||
1. Click **Send Test Notification** to send a test notification to your devices
|
||||
|
||||
## Notification Content
|
||||
|
||||
### Priority Levels
|
||||
|
||||
Pushover supports different priority levels that GoMFT uses effectively:
|
||||
|
||||
| Priority | Level | Usage in GoMFT |
|
||||
|----------|-------|----------------|
|
||||
| -2 | Lowest | Silent transfer logs, debugging info |
|
||||
| -1 | Low | Successful transfers, routine events |
|
||||
| 0 | Normal | Standard notifications |
|
||||
| 1 | High | Transfer failures, important alerts |
|
||||
| 2 | Emergency | Critical system issues |
|
||||
|
||||
Note: Emergency priority (2) notifications will repeat until acknowledged by the user.
|
||||
|
||||
### Example Notifications
|
||||
|
||||
#### Successful Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Complete: Daily Backup
|
||||
Message: Successfully transferred 123 files (1.45 GB) in 2:15
|
||||
Priority: Normal (0)
|
||||
Sound: pushover
|
||||
```
|
||||
|
||||
#### Failed Transfer
|
||||
|
||||
```
|
||||
Title: Transfer Failed: Daily Backup
|
||||
Message: Error: Connection refused to destination server
|
||||
Files: 45/123 processed
|
||||
Size: 0.5/1.45 GB transferred
|
||||
Error: Failed to connect to destination server
|
||||
Priority: High (1)
|
||||
Sound: siren
|
||||
URL: https://gomft.example.com/transfers/123
|
||||
URL Title: View Transfer Details
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Incorrect API Token/User Key**: Verify your Pushover credentials
|
||||
- **Message Rate Limiting**: Pushover has monthly message limits for free accounts
|
||||
- **Device Not Receiving**: Check device registration and network connectivity
|
||||
- **Emergency Notifications**: Verify retry/expire settings for emergency priority
|
||||
|
||||
### Pushover Logs
|
||||
|
||||
To troubleshoot notification issues:
|
||||
|
||||
1. Check the GoMFT logs: **Admin Tools** > **Logs** > filter for "pushover"
|
||||
2. Review your Pushover account's message history
|
||||
3. Check your device's Pushover app settings
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use Appropriate Priority Levels** based on event importance
|
||||
- **Reserve Emergency Priority** for truly critical issues
|
||||
- **Group Related Notifications** when possible
|
||||
- **Include Action URLs** for immediate access to relevant information
|
||||
- **Consider Sound Selection** based on notification importance
|
||||
- **Set Up Multiple Notification Methods** for critical systems
|
||||
|
||||
## Pushover vs. Other Notification Systems
|
||||
|
||||
| Feature | Pushover | Email | Gotify | Ntfy | Pushbullet |
|
||||
|---------|----------|-------|--------|------|------------|
|
||||
| Cost | Paid (one-time) | Free | Free | Free | Free/Paid |
|
||||
| Self-hosting | No | Varies | Yes | Yes | No |
|
||||
| Priority levels | Yes | No | Yes | Yes | No |
|
||||
| Acknowledgment | Yes | No | No | No | No |
|
||||
| Sound options | Yes | No | No | Limited | No |
|
||||
| Delivery guarantee | High | Varies | Good | Good | Good |
|
||||
| Device support | iOS, Android, Desktop | All | All | All | iOS, Android, Desktop |
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Webhook Notifications
|
||||
---
|
||||
|
||||
# Webhook Notifications
|
||||
|
||||
Webhook notifications in GoMFT provide a powerful way to integrate with external systems by sending HTTP requests when events occur. This enables automation workflows and integration with your existing tools and services.
|
||||
|
||||
## Overview
|
||||
|
||||
Webhooks allow GoMFT to:
|
||||
|
||||
- Send real-time notifications to external systems
|
||||
- Trigger automated workflows in third-party applications
|
||||
- Integrate with custom applications or services
|
||||
- Provide machine-readable event data (JSON or XML)
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Webhook Settings
|
||||
|
||||
To configure webhook notifications:
|
||||
|
||||
1. Navigate to **Settings** > **Notification Services** > **Webhooks**
|
||||
2. Configure the following settings:
|
||||
- **Default Webhook URL**: The base URL for webhook requests
|
||||
- **HTTP Method**: POST (default), PUT, or PATCH
|
||||
- **Content Type**: application/json (default), application/xml, or custom
|
||||
- **Authentication**: None, Basic Auth, API Key, or Bearer Token
|
||||
- **Retry Strategy**: Number of retries and delay between retries
|
||||
- **Timeout**: Maximum wait time for responses
|
||||
|
||||
### Testing Webhook Connectivity
|
||||
|
||||
After configuring your webhook settings:
|
||||
|
||||
1. Click **Test Connection** to send a test webhook request
|
||||
2. Review the response status and body from the server
|
||||
|
||||
## Webhook Payload
|
||||
|
||||
### Default JSON Payload
|
||||
|
||||
By default, GoMFT sends a JSON payload with information about the event:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_type": "transfer_completed",
|
||||
"timestamp": "2023-09-15T14:22:33Z",
|
||||
"transfer": {
|
||||
"id": "transfer-123",
|
||||
"name": "Daily Backup",
|
||||
"source": "local-server",
|
||||
"destination": "cloud-storage",
|
||||
"status": "success",
|
||||
"start_time": "2023-09-15T14:20:01Z",
|
||||
"end_time": "2023-09-15T14:22:33Z",
|
||||
"duration_seconds": 152,
|
||||
"files_transferred": 258,
|
||||
"total_size_bytes": 1073741824,
|
||||
"transfer_rate_bytes_per_second": 7064091
|
||||
},
|
||||
"schedule": {
|
||||
"id": "schedule-456",
|
||||
"name": "Daily Backup Schedule"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For failure events, additional error information is included:
|
||||
|
||||
```json
|
||||
{
|
||||
"event_type": "transfer_failed",
|
||||
"timestamp": "2023-09-15T14:22:33Z",
|
||||
"transfer": {
|
||||
"id": "transfer-123",
|
||||
"name": "Daily Backup",
|
||||
"source": "local-server",
|
||||
"destination": "cloud-storage",
|
||||
"status": "failed",
|
||||
"start_time": "2023-09-15T14:20:01Z",
|
||||
"end_time": "2023-09-15T14:22:33Z",
|
||||
"duration_seconds": 152,
|
||||
"error": {
|
||||
"code": "CONNECTION_ERROR",
|
||||
"message": "Failed to connect to destination: Connection timed out",
|
||||
"details": "TCP connection to cloud-storage:22 timed out after 60 seconds"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Payload Templates
|
||||
|
||||
You can customize the webhook payload using templates:
|
||||
|
||||
1. Navigate to the webhook configuration
|
||||
2. Switch from **Default Payload** to **Custom Payload**
|
||||
3. Edit the JSON or XML template
|
||||
|
||||
Example custom template:
|
||||
|
||||
```json
|
||||
{
|
||||
"alert": {
|
||||
"type": "{{event_type}}",
|
||||
"system": "GoMFT",
|
||||
"environment": "{{environment}}",
|
||||
"details": {
|
||||
"transfer_name": "{{transfer_name}}",
|
||||
"status": "{{status}}",
|
||||
"time": "{{timestamp}}",
|
||||
"size_mb": "{{total_size_mb}}"
|
||||
}{% if status == "failed" %},
|
||||
"error": "{{error_message}}"{% endif %}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Connection Refused**: Check network connectivity and firewall rules
|
||||
- **Authentication Failed**: Verify credentials and authentication method
|
||||
- **Timeout Issues**: Increase timeout settings for slow endpoints
|
||||
- **Invalid Payload**: Validate your custom template syntax
|
||||
- **HTTP Error Codes**: Check destination service logs for details
|
||||
|
||||
### Webhook Logs
|
||||
|
||||
GoMFT logs all webhook attempts:
|
||||
|
||||
1. Navigate to **Administartion** > **Log Viewer**
|
||||
2. Filter for "webhook" to see relevant log entries
|
||||
3. Review request and response details for troubleshooting
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use HTTPS** for all webhook endpoints
|
||||
- **Implement Retries** for important notifications
|
||||
- **Monitor Webhook Deliveries** to ensure reliability
|
||||
- **Set Up Fallback Notification Methods** for critical transfers
|
||||
- **Validate Webhook Payloads** on the receiving end
|
||||
- **Keep Webhook Processing Fast** to avoid timeouts
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Connections
|
||||
---
|
||||
|
||||
# Connection Management
|
||||
|
||||
Connections in GoMFT are configurations that define how to access different storage systems. Before you can transfer files, you need to set up connections for your source and destination systems.
|
||||
|
||||
## Supported Connection Types
|
||||
|
||||
GoMFT leverages rclone as its transfer engine, supporting a wide range of storage systems:
|
||||
|
||||
### Cloud Storage
|
||||
|
||||
- **Amazon S3**: Amazon's object storage service
|
||||
- **Google Cloud Storage**: Google's object storage service
|
||||
- **Backblaze B2**: Affordable cloud object storage
|
||||
- **Wasabi**: Hot cloud storage
|
||||
|
||||
### File Transfer Protocols
|
||||
|
||||
- **FTP**: File Transfer Protocol
|
||||
- **SFTP**: SSH File Transfer Protocol
|
||||
- **WebDAV**: Web Distributed Authoring and Versioning
|
||||
|
||||
### Local Storage
|
||||
|
||||
- **Local Disk**: Files on the server running GoMFT
|
||||
- **SMB/CIFS**: Windows file sharing
|
||||
|
||||
## Creating a Connection
|
||||
|
||||
To create a new connection:
|
||||
|
||||
1. Navigate to the **Transfer Configuration** section in the sidebar
|
||||
2. Click **+ New Configuration**
|
||||
3. Select the connection type from the dropdown menu
|
||||
4. Fill in the required details for your selected type
|
||||
5. Click **Test Source/Destination** to verify the connection works
|
||||
6. Click **Create Configuration** to store the configuration
|
||||
|
||||
## Connection Configuration Fields
|
||||
|
||||
Different connection types require different configuration fields. Here are some common examples:
|
||||
|
||||
### Amazon S3 Connection
|
||||
|
||||
- **Name**: A descriptive name for the connection
|
||||
- **Access Key ID**: AWS access key
|
||||
- **Secret Access Key**: AWS secret key
|
||||
- **Region**: AWS region (e.g., us-east-1)
|
||||
- **Endpoint**: Optional custom endpoint for S3-compatible services
|
||||
- **Bucket**: Default bucket to use (optional)
|
||||
- **Path Prefix**: Default path prefix within the bucket (optional)
|
||||
|
||||
### SFTP Connection
|
||||
|
||||
- **Name**: A descriptive name for the connection
|
||||
- **Host**: Server hostname or IP address
|
||||
- **Port**: Server port (usually 22)
|
||||
- **Username**: SFTP username
|
||||
- **Authentication Method**: Password or SSH Key
|
||||
- **Password**: User password (if using password authentication)
|
||||
- **SSH Key**: Private SSH key (if using key authentication)
|
||||
- **SSH Key Passphrase**: Passphrase for SSH key (if applicable)
|
||||
|
||||
### Local Storage Connection
|
||||
|
||||
- **Name**: A descriptive name for the connection
|
||||
- **Path**: Base path on the local filesystem
|
||||
|
||||
## Connection Security
|
||||
|
||||
GoMFT follows best practices for handling connection credentials:
|
||||
|
||||
- **Encryption**: All sensitive credentials are encrypted at rest
|
||||
- **Access Control**: Connections are protected by user permissions
|
||||
- **Masked Values**: Passwords and secret keys are masked in the UI
|
||||
- **Key Management**: SSH keys and other credentials are securely stored
|
||||
|
||||
## Managing Connections
|
||||
|
||||
### Viewing Connections
|
||||
|
||||
The **Transfer Configurations** page displays all configured connections with:
|
||||
- Configuration name
|
||||
- Configuration type
|
||||
- Last updated date
|
||||
|
||||
### Editing Transfer Confirgurations
|
||||
|
||||
To edit an existing connection:
|
||||
1. Navigate to the **Transfer Confiruations** section
|
||||
2. Find the config you want to edit
|
||||
3. Click the **Edit** button
|
||||
4. Modify the config details
|
||||
5. Test the updated configuration
|
||||
6. Save your changes
|
||||
|
||||
### Deleting Transfer Configurations
|
||||
|
||||
To delete a connection:
|
||||
1. Navigate to the **Transfer Configurations** section
|
||||
2. Find the config you want to delete
|
||||
3. Click the **Delete** button
|
||||
4. Confirm the deletion
|
||||
|
||||
**Note**: You cannot delete connections that are in use by active transfers or schedules.
|
||||
|
||||
## Testing Transfer Configurations
|
||||
|
||||
GoMFT includes a configuration testing feature to verify connectivity:
|
||||
|
||||
1. After entering details for a configuration, click **Test Source/Destination**
|
||||
2. GoMFT will attempt to authenticate with the remote system
|
||||
3. For file storage, it will also verify read/write permissions
|
||||
4. Results will display showing success or failure details
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use descriptive names** for connections to easily identify them
|
||||
- **Test connections regularly** to ensure they still work
|
||||
- **Rotate credentials** periodically for enhanced security
|
||||
- **Use service accounts** rather than personal accounts when possible
|
||||
- **Document connection details** in the description field
|
||||
- **Use the minimal required permissions** for enhanced security
|
||||
- **Organize connections** using consistent naming conventions
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Monitoring
|
||||
---
|
||||
|
||||
# Monitoring and Reporting
|
||||
|
||||
GoMFT provides comprehensive monitoring and reporting features to help you track transfer activities, analyze performance, and ensure reliable operation. This page explains the monitoring tools available in GoMFT.
|
||||
|
||||
## Dashboard
|
||||
|
||||
The GoMFT dashboard provides a real-time overview of your file transfer system:
|
||||
|
||||
### Dashboard Components
|
||||
|
||||
- **Transfer Status**: Overview of currently running, completed, and failed transfers
|
||||
- **Recent Transfers**: List of the most recent transfer executions
|
||||
- **System Health**: Indicators for system health and resource usage
|
||||
- **Quick Actions**: Buttons for common tasks like creating transfers or checking logs
|
||||
|
||||
To access the dashboard:
|
||||
1. Log in to GoMFT
|
||||
2. The dashboard is the default landing page
|
||||
3. You can return to it anytime by clicking **Dashboard** in the sidebar
|
||||
|
||||
## Transfer History
|
||||
|
||||
The transfer history section provides detailed information about all transfer executions:
|
||||
|
||||
### Transfer History Features
|
||||
|
||||
- **Comprehensive Logs**: Complete transfer history with filtering options
|
||||
- **Status Tracking**: Visual indicators for transfer status (successful, failed, in progress)
|
||||
- **Performance Metrics**: Data on transfer speed, file counts, and total bytes
|
||||
- **Time Tracking**: Start time, end time, and duration for all transfers
|
||||
- **Filter and Search**: Find specific transfers by name, status, date, or other criteria
|
||||
|
||||
To access transfer history:
|
||||
1. Navigate to **Transfer History** in the sidebar
|
||||
2. Use filters to narrow down the list of transfers
|
||||
3. Click on any transfer to see detailed information
|
||||
|
||||
## Real-Time Monitoring
|
||||
|
||||
GoMFT provides real-time monitoring of active transfers:
|
||||
|
||||
### Active Transfers
|
||||
|
||||
- **Live Progress**: See transfer progress as it happens
|
||||
- **File Counters**: Track files transferred, remaining, and skipped
|
||||
- **Bandwidth Usage**: Monitor current transfer speeds
|
||||
- **Cancel Option**: Ability to cancel running transfers
|
||||
- **Log Streaming**: View logs as they're generated
|
||||
|
||||
To monitor active transfers:
|
||||
1. Navigate to **Transfer History** in the sidebar
|
||||
2. View all currently running transfers
|
||||
3. Click on any transfer to see detailed progress
|
||||
|
||||
## Detailed Transfer Logs
|
||||
|
||||
For each transfer execution, GoMFT maintains detailed logs:
|
||||
|
||||
### Log Information
|
||||
|
||||
- **File Details**: Information about each transferred file
|
||||
- **Error Messages**: Detailed error information for failed transfers
|
||||
- **Warning Messages**: Warnings that occurred during transfer
|
||||
- **Transfer Summary**: Overall summary of the transfer operation
|
||||
- **Performance Data**: Transfer rates and timing information
|
||||
|
||||
To access detailed logs:
|
||||
1. Navigate to **Transfer History** in the sidebar
|
||||
2. Find the transfer of interest
|
||||
3. Click on **View Details** to open details
|
||||
|
||||
## System Monitoring
|
||||
|
||||
GoMFT monitors the health and performance of the system itself:
|
||||
|
||||
## Alerts and Notifications
|
||||
|
||||
GoMFT can alert you to important events:
|
||||
|
||||
### Alert Types
|
||||
|
||||
- **Transfer Failures**: Notifications when transfers fail
|
||||
- **Transfer Completion**: Alerts when transfers complete
|
||||
|
||||
To configure alerts:
|
||||
1. Navigate to **Notification Providers**
|
||||
2. Set up notification methods (email, webhook, gotify, ntfy, pushover, pushbullet)
|
||||
4. Configure alert severity levels
|
||||
|
||||
## Export and API Access
|
||||
|
||||
GoMFT allows you to export monitoring data:
|
||||
|
||||
### Export Options
|
||||
|
||||
- **CSV Export**: Download transfer history in CSV format
|
||||
- **JSON Export**: Export data in JSON format for further processing
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Review the dashboard daily** to stay informed of transfer status
|
||||
- **Set up alerts** for critical transfers to be notified of failures
|
||||
- **Generate regular reports** for compliance and performance tracking
|
||||
- **Monitor system health** to prevent resource issues
|
||||
- **Archive logs** for long-term storage and compliance
|
||||
- **Use filters** to focus on the most important information
|
||||
- **Export data** for backup and external analysis
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Schedules
|
||||
---
|
||||
|
||||
# Schedule Management
|
||||
|
||||
GoMFT's scheduling system allows you to automate file transfers to run at specific times or on a recurring basis. This section explains how to create, manage, and monitor scheduled transfers.
|
||||
|
||||
## Schedule Types
|
||||
|
||||
GoMFT supports several types of schedules:
|
||||
|
||||
### One-Time Schedules
|
||||
|
||||
Run a transfer once at a specific date and time.
|
||||
|
||||
### Recurring Schedules
|
||||
|
||||
Run a transfer repeatedly according to a defined pattern:
|
||||
|
||||
- **Hourly**: Run every hour at a specific minute
|
||||
- **Daily**: Run every day at a specific time
|
||||
- **Weekly**: Run on specific days of the week
|
||||
- **Monthly**: Run on specific days of the month
|
||||
- **Custom**: Define a custom schedule using cron syntax
|
||||
|
||||
## Creating a Schedule
|
||||
|
||||
To create a new schedule:
|
||||
|
||||
1. Navigate to the **Schedules** section in the sidebar
|
||||
2. Click **Create New Schedule**
|
||||
3. Select the transfer to schedule
|
||||
4. Choose the schedule type
|
||||
5. Configure the schedule details
|
||||
6. Set additional options
|
||||
7. Click **Save Schedule**
|
||||
|
||||
## Schedule Configuration
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
- **Name**: A descriptive name for the schedule
|
||||
- **Transfer**: The transfer configuration to run
|
||||
- **Enabled**: Toggle to enable or disable the schedule
|
||||
- **Schedule Type**: One-time or recurring
|
||||
|
||||
### One-Time Schedule Options
|
||||
|
||||
- **Date**: The date to run the transfer
|
||||
- **Time**: The time to run the transfer
|
||||
|
||||
### Recurring Schedule Options
|
||||
|
||||
#### Simple Options
|
||||
|
||||
- **Frequency**: Hourly, Daily, Weekly, Monthly, or Custom
|
||||
- **Time**: The time to run (for Daily, Weekly, Monthly)
|
||||
- **Days**: The days to run (for Weekly, Monthly)
|
||||
- **Minutes**: The minute to run (for Hourly)
|
||||
|
||||
#### Advanced Options (Cron Syntax)
|
||||
|
||||
For more complex scheduling needs, you can use cron syntax:
|
||||
|
||||
```
|
||||
┌─────────── minute (0 - 59)
|
||||
│ ┌──────── hour (0 - 23)
|
||||
│ │ ┌────── day of month (1 - 31)
|
||||
│ │ │ ┌──── month (1 - 12)
|
||||
│ │ │ │ ┌── day of week (0 - 6) (Sunday to Saturday)
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
│ │ │ │ │
|
||||
* * * * *
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `0 2 * * *`: Every day at 2:00 AM
|
||||
- `0 9-17 * * 1-5`: Every hour from 9 AM to 5 PM, Monday to Friday
|
||||
- `*/15 * * * *`: Every 15 minutes
|
||||
- `0 0 1,15 * *`: 1st and 15th of every month at midnight
|
||||
|
||||
### Additional Options
|
||||
|
||||
- **Timeout**: Maximum duration for the transfer (after which it will be terminated)
|
||||
- **Retry Count**: Number of times to retry on failure
|
||||
- **Retry Delay**: Time to wait between retry attempts
|
||||
- **Priority**: Schedule priority (higher priority schedules run first when multiple are due)
|
||||
- **Description**: Additional notes about the schedule
|
||||
|
||||
## Schedule Groups
|
||||
|
||||
GoMFT allows you to organize schedules into logical groups:
|
||||
|
||||
1. Navigate to **Schedule Groups** in the Schedules section
|
||||
2. Create a new group with a name and description
|
||||
3. Assign schedules to the group
|
||||
4. View and manage grouped schedules together
|
||||
|
||||
Benefits of groups:
|
||||
- Organize related schedules
|
||||
- Apply batch operations to multiple schedules
|
||||
- Monitor group-level statistics
|
||||
|
||||
## Managing Schedules
|
||||
|
||||
### Viewing Schedules
|
||||
|
||||
The **Schedules** page displays all configured schedules with:
|
||||
- Schedule name
|
||||
- Associated transfer
|
||||
- Next run time
|
||||
- Last run status
|
||||
- Enabled/disabled status
|
||||
|
||||
### Editing Scheduled Jobs
|
||||
|
||||
To edit an existing schedule:
|
||||
1. Navigate to the **Scheduled Jobs** section
|
||||
2. Find the schedule you want to edit
|
||||
3. Click the **Edit** button
|
||||
4. Modify the schedule details
|
||||
5. Save your changes
|
||||
|
||||
### Enabling/Disabling Scheduled Jobs
|
||||
|
||||
To temporarily disable a schedule without deleting it:
|
||||
1. Navigate to the **Scheduled Job** section
|
||||
2. Find the schedule you want to disable
|
||||
3. Click edit
|
||||
3. Toggle the **Enabled** switch to Off and save
|
||||
4. The schedule will remain configured but won't run until re-enabled
|
||||
|
||||
### Deleting Schedules
|
||||
|
||||
To delete a schedule:
|
||||
1. Navigate to the **Scheduled Job** section
|
||||
2. Find the schedule you want to delete
|
||||
3. Click the **Delete** button
|
||||
4. Confirm the deletion
|
||||
|
||||
## Schedule Execution
|
||||
|
||||
When a schedule runs, GoMFT performs these actions:
|
||||
|
||||
1. Identifies schedules due for execution
|
||||
2. Prioritizes schedules based on priority setting
|
||||
3. Creates execution jobs for the associated transfers
|
||||
4. Monitors job execution
|
||||
5. Records results in the history
|
||||
6. Handles retries if configured and needed
|
||||
7. Updates next run time for recurring schedules
|
||||
|
||||
## Monitoring Schedules
|
||||
|
||||
GoMFT provides several ways to monitor your scheduled transfers:
|
||||
|
||||
<!-- ### Schedule Calendar
|
||||
|
||||
View all scheduled transfers in a calendar view:
|
||||
1. Navigate to **Schedule Calendar** in the Schedules section
|
||||
2. See all upcoming scheduled transfers in a monthly, weekly, or daily view
|
||||
3. Click on any scheduled transfer to see details or edit it -->
|
||||
|
||||
### Transfer History
|
||||
|
||||
View the execution history of your schedules:
|
||||
1. Navigate to **Transfer History** on the sidebar
|
||||
2. See when schedules ran, their status, and execution details
|
||||
3. Filter by date range, status, or schedule name
|
||||
|
||||
## Schedule Notifications
|
||||
|
||||
Configure notifications for scheduled transfers:
|
||||
|
||||
1. Edit a schedule
|
||||
2. Navigate to the **Notifications** tab
|
||||
3. Configure email notifications or webhooks
|
||||
4. Specify notification conditions (success, failure, or both)
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use descriptive names** for schedules to easily identify them
|
||||
- **Set appropriate timeouts** based on expected transfer duration
|
||||
- **Configure retries** for critical transfers
|
||||
- **Use schedule groups** to organize related schedules
|
||||
- **Stagger schedules** to avoid resource contention
|
||||
- **Set up notifications** for critical schedules
|
||||
- **Review schedule history** regularly to identify issues
|
||||
- **Disable schedules** instead of deleting them for temporary pauses
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Transfers
|
||||
---
|
||||
|
||||
# Transfer Operations
|
||||
|
||||
GoMFT's primary function is to manage file transfers between different storage systems. This page explains the transfer operations available in GoMFT and how to configure them.
|
||||
|
||||
## Transfer Types
|
||||
|
||||
GoMFT supports several types of transfer operations, each with different behaviors:
|
||||
|
||||
### Copy
|
||||
|
||||
The **Copy** operation copies files from the source to the destination. Files are only copied if they don't exist at the destination or if they've been modified at the source.
|
||||
|
||||
```
|
||||
Source → Destination
|
||||
```
|
||||
|
||||
### Sync
|
||||
|
||||
The **Sync** operation makes the destination identical to the source, adding, removing, and updating files as necessary.
|
||||
|
||||
```
|
||||
Source → Destination (with deletions)
|
||||
```
|
||||
|
||||
### Move
|
||||
|
||||
The **Move** operation copies files from the source to the destination and then deletes the source files after a successful transfer.
|
||||
|
||||
```
|
||||
Source → Destination → Delete Source
|
||||
```
|
||||
|
||||
### Bidirectional Sync
|
||||
|
||||
The **Bidirectional Sync** operation synchronizes files in both directions, ensuring that the newest version of each file is present in both locations.
|
||||
|
||||
```
|
||||
Source ⟷ Destination
|
||||
```
|
||||
|
||||
## Transfer Configuration
|
||||
|
||||
When creating a transfer in GoMFT, you need to configure the following elements:
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
- **Name**: A descriptive name for the transfer
|
||||
- **Description**: Optional details about the transfer's purpose
|
||||
- **Source**: The source connection and path
|
||||
- **Destination**: The destination connection and path
|
||||
- **Transfer Type**: Copy, Sync, Move, or Bidirectional Sync
|
||||
|
||||
### Advanced Options
|
||||
|
||||
#### File Selection
|
||||
|
||||
- **Include Patterns**: Patterns for files to include (e.g., `*.txt`, `data/**/*.csv`)
|
||||
- **Exclude Patterns**: Patterns for files to exclude (e.g., `*.tmp`, `**/._*`)
|
||||
- **Min Size**: Minimum file size to transfer
|
||||
- **Max Size**: Maximum file size to transfer
|
||||
- **Min Age**: Only transfer files older than this
|
||||
- **Max Age**: Only transfer files newer than this
|
||||
|
||||
#### Transfer Behavior
|
||||
|
||||
- **Checksum**: Compare files using checksums instead of size/date
|
||||
- **Delete Before**: Delete destination files before transferring
|
||||
- **Delete During**: Delete destination files during transfer
|
||||
- **Delete After**: Delete destination files not in source after transfer
|
||||
- **Update Existing**: Update existing files at destination
|
||||
- **Skip New**: Skip new files not present at destination
|
||||
- **Skip Newer**: Skip files that are newer at the destination
|
||||
|
||||
#### Performance Options
|
||||
|
||||
- **Transfers**: Number of concurrent file transfers
|
||||
- **Checkers**: Number of concurrent file checkers
|
||||
- **Bandwidth Limit**: Maximum bandwidth to use in bytes/s
|
||||
- **Buffer Size**: Size of transfer buffer (default: 16MB)
|
||||
- **Chunk Size**: Upload chunk size for chunked uploads
|
||||
|
||||
## Transfer Execution
|
||||
|
||||
### Manual Execution
|
||||
|
||||
Transfers can be run on-demand:
|
||||
|
||||
1. Navigate to the **Scheduled Jobs** section
|
||||
2. Find your job in the list
|
||||
3. Click **Run Now**
|
||||
4. Monitor the job progress in real-time
|
||||
|
||||
### Scheduled Execution
|
||||
|
||||
Transfers can be scheduled to run automatically:
|
||||
|
||||
1. Navigate to the **Scheduled Jobs** section
|
||||
2. Create a new schedule linked to your transfer configuration
|
||||
3. Set up the schedule using cron syntax or the schedule builder
|
||||
4. The transfer will run automatically according to the schedule
|
||||
|
||||
## Transfer Monitoring
|
||||
|
||||
### Status Indicators
|
||||
|
||||
- **Pending**: Transfer is waiting to start
|
||||
- **Running**: Transfer is in progress
|
||||
- **Completed**: Transfer finished successfully
|
||||
- **Failed**: Transfer encountered an error
|
||||
- **Canceled**: Transfer was manually canceled
|
||||
|
||||
### Transfer Details
|
||||
|
||||
For each transfer execution, GoMFT records:
|
||||
|
||||
- Start and end times
|
||||
- Duration
|
||||
- Number of files transferred
|
||||
- Total bytes transferred
|
||||
- Files skipped
|
||||
- Errors encountered
|
||||
- Detailed logs
|
||||
|
||||
## Transfer Logs
|
||||
|
||||
GoMFT provides detailed logs for each transfer:
|
||||
|
||||
1. Navigate to **Transfer History**
|
||||
2. Click on a **View Details** button on the transfer entry
|
||||
|
||||
The logs include information about:
|
||||
|
||||
- Each file transferred
|
||||
- Skipped files
|
||||
- Errors
|
||||
- Performance metrics
|
||||
- Overall transfer summary
|
||||
|
||||
## Troubleshooting Failed Transfers
|
||||
|
||||
When a transfer fails, GoMFT provides information to help identify the cause:
|
||||
|
||||
1. Check the error message in the transfer history
|
||||
2. Review the detailed logs for the specific error
|
||||
3. Common issues include:
|
||||
- Permission problems
|
||||
- Network connectivity
|
||||
- Invalid credentials
|
||||
- Path not found
|
||||
- Disk space issues
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Use meaningful names** for your transfers to easily identify them
|
||||
- **Start small** when testing new configurations
|
||||
- **Use include/exclude patterns** to limit scope when working with large directories
|
||||
- **Set appropriate concurrency** based on network conditions and system resources
|
||||
- **Use checksumming** for critical data to ensure integrity
|
||||
- **Set bandwidth limits** to avoid network congestion during peak hours
|
||||
- **Schedule large transfers** during off-peak times
|
||||
- **Use notifications** to stay informed about transfer results
|
||||
- **Regularly review logs** to identify potential issues
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Code Review Guidelines
|
||||
---
|
||||
|
||||
# Code Review Guidelines
|
||||
|
||||
This document outlines the code review process and expectations for the GoMFT project.
|
||||
|
||||
## Purpose of Code Reviews
|
||||
|
||||
Code reviews serve several important purposes:
|
||||
|
||||
- Ensuring code quality and consistency
|
||||
- Identifying bugs, edge cases, and potential issues early
|
||||
- Sharing knowledge among team members
|
||||
- Ensuring adherence to project standards and best practices
|
||||
- Validating that the implementation meets requirements
|
||||
|
||||
## Code Review Process
|
||||
|
||||
### 1. Before Requesting a Review
|
||||
|
||||
Before requesting a review, ensure your code:
|
||||
|
||||
- Passes all automated tests
|
||||
- Follows the project's coding standards
|
||||
- Is well-documented
|
||||
- Includes appropriate tests
|
||||
- Has a clear, descriptive PR title and description
|
||||
|
||||
### 2. Requesting a Review
|
||||
|
||||
- Create a pull request against the appropriate branch
|
||||
- Fill out the PR template completely
|
||||
- Tag appropriate reviewers based on the code being changed
|
||||
- Respond to any automated CI/CD feedback
|
||||
|
||||
### 3. Conducting a Review
|
||||
|
||||
When reviewing code, focus on:
|
||||
|
||||
#### Code Quality
|
||||
- Is the code readable and maintainable?
|
||||
- Does it follow project conventions and patterns?
|
||||
- Is the implementation efficient?
|
||||
- Are edge cases handled appropriately?
|
||||
|
||||
#### Functionality
|
||||
- Does the code meet the requirements?
|
||||
- Does it handle error conditions properly?
|
||||
- Is the user experience considered?
|
||||
|
||||
#### Testing
|
||||
- Are there sufficient tests?
|
||||
- Do tests cover edge cases?
|
||||
- Are tests reliable (not flaky)?
|
||||
|
||||
#### Security
|
||||
- Are there potential security issues?
|
||||
- Is user input properly validated?
|
||||
- Are credentials or sensitive data handled securely?
|
||||
|
||||
#### Documentation
|
||||
- Is the code well-documented?
|
||||
- Are public APIs clearly documented?
|
||||
- Is the documentation accurate and up-to-date?
|
||||
|
||||
### 4. Providing Feedback
|
||||
|
||||
When providing feedback:
|
||||
|
||||
- Be specific and clear
|
||||
- Offer suggestions for improvement
|
||||
- Differentiate between required changes and optional suggestions
|
||||
- Provide context or reasoning for requested changes
|
||||
- Be constructive and respectful
|
||||
|
||||
Use these comment prefixes to indicate the severity of feedback:
|
||||
|
||||
- **Blocker:** Must be addressed before merging
|
||||
- **Suggestion:** Recommended improvement, but not required
|
||||
- **Question:** Request for clarification
|
||||
- **Nitpick:** Minor style or formatting issue
|
||||
- **Praise:** Highlight particularly good code
|
||||
|
||||
### 5. Responding to Feedback
|
||||
|
||||
When receiving review feedback:
|
||||
|
||||
- Address all comments
|
||||
- Explain your reasoning if you disagree with a suggestion
|
||||
- Ask for clarification if needed
|
||||
- Thank reviewers for their input
|
||||
- Mark resolved comments as such
|
||||
|
||||
### 6. Approving and Merging
|
||||
|
||||
A PR can be merged when:
|
||||
|
||||
- It has received approval from at least one reviewer
|
||||
- All "Blocker" issues are resolved
|
||||
- All automated checks are passing
|
||||
- The PR has been rebased on the latest target branch
|
||||
|
||||
## Best Practices for Reviewers
|
||||
|
||||
### Focus on the Important Things
|
||||
- Prioritize correctness, security, and maintainability
|
||||
- Don't get too caught up in style issues that could be automated
|
||||
- Consider the big picture and overall architecture
|
||||
|
||||
### Be Timely
|
||||
- Try to review PRs within 1-2 business days
|
||||
- If you can't review promptly, let the author know or reassign
|
||||
- For urgent fixes, prioritize those reviews
|
||||
|
||||
### Be Thorough
|
||||
- Take the time to understand the code
|
||||
- Test the code locally if necessary
|
||||
- Consider edge cases and failure modes
|
||||
|
||||
### Be Respectful
|
||||
- Focus on the code, not the person
|
||||
- Phrase feedback as suggestions or questions
|
||||
- Acknowledge good work and improvements
|
||||
|
||||
## Best Practices for Authors
|
||||
|
||||
### Keep PRs Focused
|
||||
- Each PR should address a single concern
|
||||
- Large changes should be broken into smaller, logical PRs
|
||||
- Avoid unrelated changes in a PR
|
||||
|
||||
### Provide Context
|
||||
- Explain the purpose and approach in the PR description
|
||||
- Link to relevant issues or documentation
|
||||
- Point out areas where you're uncertain or would like specific feedback
|
||||
|
||||
### Respond Promptly
|
||||
- Address feedback in a timely manner
|
||||
- Ask questions if feedback is unclear
|
||||
- Be open to suggestions and alternatives
|
||||
|
||||
### Test Thoroughly
|
||||
- Test your changes locally before requesting review
|
||||
- Consider edge cases and error scenarios
|
||||
- Update tests to cover new functionality
|
||||
|
||||
## Special Considerations
|
||||
|
||||
### Security-Related Changes
|
||||
- Security-focused changes require extra scrutiny
|
||||
- At least one reviewer should have security expertise
|
||||
- Consider potential attack vectors and edge cases
|
||||
|
||||
### API Changes
|
||||
- Changes to public APIs require careful review
|
||||
- Consider backward compatibility
|
||||
- Ensure API changes are well-documented
|
||||
|
||||
### Database Changes
|
||||
- Review for potential performance issues
|
||||
- Consider migration strategy and backward compatibility
|
||||
- Validate data integrity considerations
|
||||
|
||||
### UI Changes
|
||||
- Consider accessibility implications
|
||||
- Review for consistency with design standards
|
||||
- Test on different devices and screen sizes
|
||||
|
||||
## Learning from Code Reviews
|
||||
|
||||
Code reviews are a learning opportunity:
|
||||
|
||||
- Take note of recurring feedback to improve future code
|
||||
- Share knowledge gained from reviews with the team
|
||||
- Use reviews to identify areas where documentation or guides could be improved
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
### General
|
||||
- [ ] Code is well-structured and follows project patterns
|
||||
- [ ] Variables and functions have clear, descriptive names
|
||||
- [ ] Comments explain "why" not just "what"
|
||||
- [ ] Unnecessary code is removed (commented code, debug logs)
|
||||
- [ ] No hardcoded values that should be configurable
|
||||
|
||||
### Go-Specific
|
||||
- [ ] Error handling is appropriate and consistent
|
||||
- [ ] Follows Go idioms and best practices
|
||||
- [ ] Concurrent code is safe and efficient
|
||||
- [ ] Uses appropriate Go standard library functions
|
||||
- [ ] Properly handles resources (file handles, connections)
|
||||
|
||||
### Frontend-Specific
|
||||
- [ ] UI is responsive and accessible
|
||||
- [ ] HTMX usage follows project patterns
|
||||
- [ ] Templ templates are clean and maintainable
|
||||
- [ ] JavaScript is minimal and follows best practices
|
||||
- [ ] CSS follows project conventions
|
||||
|
||||
### Testing
|
||||
- [ ] Tests are included for new functionality
|
||||
- [ ] Tests cover edge cases and error paths
|
||||
- [ ] Tests are clear and maintainable
|
||||
- [ ] Mocks and fixtures are used appropriately
|
||||
|
||||
### Security
|
||||
- [ ] Input validation is thorough
|
||||
- [ ] No SQL injection vulnerabilities
|
||||
- [ ] Authentication and authorization are properly implemented
|
||||
- [ ] Sensitive data is handled securely
|
||||
|
||||
### Performance
|
||||
- [ ] Code is efficient for expected scale
|
||||
- [ ] Database queries are optimized
|
||||
- [ ] Appropriate caching is used
|
||||
- [ ] Resources are used efficiently
|
||||
|
||||
Remember that code reviews are a collaborative process aimed at improving the overall quality of the codebase. Both reviewers and authors should approach the process with a growth mindset and mutual respect.
|
||||
@@ -0,0 +1,278 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Contributing
|
||||
---
|
||||
|
||||
# Contributing to GoMFT
|
||||
|
||||
Thank you for your interest in contributing to GoMFT! This guide will help you get started with contributing to the project.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following installed:
|
||||
|
||||
- **Go** (version 1.20 or later)
|
||||
- **Node.js** (version 18 or later)
|
||||
- **Git**
|
||||
- **Docker** (optional, for container-based development)
|
||||
|
||||
### Setting Up the Development Environment
|
||||
|
||||
1. Fork the repository on GitHub.
|
||||
|
||||
2. Clone your forked repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/GoMFT.git
|
||||
cd GoMFT
|
||||
```
|
||||
|
||||
3. Add the original repository as an upstream remote:
|
||||
|
||||
```bash
|
||||
git remote add upstream https://github.com/StarFleetCPTN/GoMFT.git
|
||||
```
|
||||
|
||||
4. Install Go dependencies:
|
||||
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
5. Install Node.js dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
6. Install the Templ compiler:
|
||||
|
||||
```bash
|
||||
go install github.com/a-h/templ/cmd/templ@latest
|
||||
```
|
||||
|
||||
7. Install Air for live reloading during development:
|
||||
|
||||
```bash
|
||||
go install github.com/cosmtrek/air@latest
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. Create a new branch for your feature or bug fix:
|
||||
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. Make your changes to the codebase.
|
||||
|
||||
3. Compile the Templ templates:
|
||||
|
||||
```bash
|
||||
templ generate
|
||||
```
|
||||
|
||||
4. Run the development server with Air:
|
||||
|
||||
```bash
|
||||
air
|
||||
```
|
||||
|
||||
This will start the application with hot reloading enabled, so changes to Go files will trigger a rebuild.
|
||||
|
||||
5. For frontend development, compile the Tailwind CSS and watch for changes:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
6. Access the application at `http://localhost:8080`.
|
||||
|
||||
## Project Structure
|
||||
|
||||
See the [Project Structure](/docs/development/project-structure) page for a detailed overview of the codebase organization.
|
||||
|
||||
## Coding Guidelines
|
||||
|
||||
### Go Code
|
||||
|
||||
- Follow the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) and [Effective Go](https://golang.org/doc/effective_go) guidelines.
|
||||
- Format your code with `gofmt` or `go fmt`.
|
||||
- Ensure your code passes `golint` and `go vet`.
|
||||
- Write tests for your functionality.
|
||||
- Add comments to exported functions, types, and packages.
|
||||
|
||||
### Frontend Code
|
||||
|
||||
- Follow the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) for JavaScript code.
|
||||
- Use Tailwind CSS for styling.
|
||||
- Ensure your UI components are responsive.
|
||||
- Test your UI changes in different browsers.
|
||||
|
||||
### Commit Messages
|
||||
|
||||
- Use clear and meaningful commit messages.
|
||||
- Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
||||
- `feat`: A new feature
|
||||
- `fix`: A bug fix
|
||||
- `docs`: Documentation only changes
|
||||
- `style`: Changes that do not affect the meaning of the code
|
||||
- `refactor`: A code change that neither fixes a bug nor adds a feature
|
||||
- `test`: Adding missing tests or correcting existing tests
|
||||
- `chore`: Changes to the build process or auxiliary tools
|
||||
- `perf`: Performance improvements
|
||||
|
||||
Example: `feat: add email notification for failed transfers`
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
Run the Go tests:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Run specific tests:
|
||||
|
||||
```bash
|
||||
go test ./internal/api/...
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
- Write unit tests for your functions and methods.
|
||||
- Write integration tests for API endpoints.
|
||||
- Aim for high test coverage, especially for critical functionality.
|
||||
- Use table-driven tests where appropriate.
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Update your branch with the latest changes from upstream:
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
2. Push your branch to your forked repository:
|
||||
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
3. Create a pull request from your branch to the main repository.
|
||||
|
||||
4. Ensure your PR description clearly describes the changes you've made.
|
||||
|
||||
5. Link any relevant issues in your PR description.
|
||||
|
||||
6. Wait for code review and address any feedback.
|
||||
|
||||
### PR Review Checklist
|
||||
|
||||
Before submitting your PR, please ensure:
|
||||
|
||||
- [ ] Your code builds without errors or warnings
|
||||
- [ ] You've added tests for your changes
|
||||
- [ ] All tests pass
|
||||
- [ ] Your code follows the project's coding guidelines
|
||||
- [ ] You've updated documentation as needed
|
||||
- [ ] You've added appropriate logging
|
||||
- [ ] You've considered security implications
|
||||
- [ ] Your changes don't introduce performance regressions
|
||||
|
||||
## Development Tips
|
||||
|
||||
### Working with Templ
|
||||
|
||||
[Templ](https://github.com/a-h/templ) is used for HTML templating in GoMFT. After making changes to `.templ` files, you need to regenerate the Go code:
|
||||
|
||||
```bash
|
||||
templ generate
|
||||
```
|
||||
|
||||
### Working with HTMX
|
||||
|
||||
[HTMX](https://htmx.org/) is used for dynamic UI updates. Familiarize yourself with its concepts before making UI changes.
|
||||
|
||||
### Working with SQLite
|
||||
|
||||
GoMFT uses SQLite for data storage. The database file is located at `data/gomft.db` by default. You can use a tool like [SQLite Browser](https://sqlitebrowser.org/) to inspect the database.
|
||||
|
||||
### Debugging
|
||||
|
||||
For debugging Go code, you can use:
|
||||
|
||||
- `fmt.Printf()` statements for simple debugging
|
||||
- [Delve](https://github.com/go-delve/delve) for more complex debugging scenarios
|
||||
- VSCode's integrated Go debugger
|
||||
|
||||
## Documentation
|
||||
|
||||
### Updating Documentation
|
||||
|
||||
Documentation is written in Markdown and stored in the `docs/` directory. To update the documentation:
|
||||
|
||||
1. Edit the relevant Markdown files.
|
||||
2. If you're adding new pages, update the sidebar configuration in `sidebars.ts`.
|
||||
3. Preview your changes using the documentation development server:
|
||||
|
||||
```bash
|
||||
cd documentation
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
4. Access the documentation at `http://localhost:3000`.
|
||||
|
||||
### API Documentation
|
||||
|
||||
API documentation is generated from Go comments using [Swaggo](https://github.com/swaggo/swag). To update the API documentation:
|
||||
|
||||
1. Update the API comments following the Swagger/OpenAPI format.
|
||||
2. Regenerate the API documentation:
|
||||
|
||||
```bash
|
||||
swag init -g cmd/api/main.go
|
||||
```
|
||||
|
||||
## Release Process
|
||||
|
||||
GoMFT follows [Semantic Versioning](https://semver.org/).
|
||||
|
||||
### Creating a Release
|
||||
|
||||
1. Update the version number in relevant files:
|
||||
- `VERSION` file
|
||||
- `package.json`
|
||||
- `internal/version/version.go`
|
||||
|
||||
2. Update the CHANGELOG.md file with the new version and its changes.
|
||||
|
||||
3. Create a new tag:
|
||||
|
||||
```bash
|
||||
git tag -a v1.2.3 -m "Release v1.2.3"
|
||||
git push origin v1.2.3
|
||||
```
|
||||
|
||||
4. The CI/CD pipeline will build and publish the release artifacts.
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you need help with contributing to GoMFT, you can:
|
||||
|
||||
- Open an issue on GitHub with questions
|
||||
- Discuss in the GitHub Discussions section
|
||||
- Reach out to the maintainers
|
||||
|
||||
Thank you for contributing to GoMFT!
|
||||
@@ -0,0 +1,216 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Project Structure
|
||||
---
|
||||
|
||||
# Project Structure
|
||||
|
||||
This page explains the structure of the GoMFT codebase to help developers understand how the application is organized.
|
||||
|
||||
## Overview
|
||||
|
||||
GoMFT is built using a combination of Go for the backend and web technologies for the frontend. The application follows a modular architecture to maintain separation of concerns and facilitate testing and maintenance.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Here's the high-level directory structure of the GoMFT project:
|
||||
|
||||
```
|
||||
.
|
||||
├── components/ # Templ components for UI
|
||||
├── internal/
|
||||
│ ├── api/ # REST API handlers
|
||||
│ ├── auth/ # Authentication/authorization
|
||||
│ ├── config/ # Configuration management
|
||||
│ ├── db/ # Database models and operations
|
||||
│ ├── email/ # Email service for notifications and password resets
|
||||
│ ├── scheduler/ # Job scheduling and execution
|
||||
│ └── web/ # Web interface handlers
|
||||
├── static/ # Static assets
|
||||
│ ├── css/
|
||||
│ └── js/
|
||||
└── main.go # Application entry point
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### Backend (Go)
|
||||
|
||||
GoMFT's backend is written in Go and structured around several key packages:
|
||||
|
||||
#### `main.go`
|
||||
|
||||
The entry point for the application. It initializes the application, loads configuration, sets up the database, and starts the web server.
|
||||
|
||||
#### `internal/`
|
||||
|
||||
Contains all internal packages that are not intended to be imported by other applications.
|
||||
|
||||
- **`api/`**: REST API implementation
|
||||
- `handlers/`: API request handlers
|
||||
- `middleware/`: API middleware (authentication, logging, etc.)
|
||||
- `routes.go`: API route definitions
|
||||
|
||||
- **`auth/`**: Authentication and authorization
|
||||
- `providers/`: Authentication providers (local, LDAP, OAuth)
|
||||
- `middleware/`: Authentication middleware
|
||||
- `rbac/`: Role-based access control
|
||||
|
||||
- **`config/`**: Configuration management
|
||||
- `config.go`: Application configuration structure
|
||||
- `env.go`: Environment variable loading
|
||||
- `file.go`: Configuration file loading
|
||||
|
||||
- **`db/`**: Database layer
|
||||
- `models/`: Database model definitions
|
||||
- `migrations/`: Database schema migrations
|
||||
- `repositories/`: Data access methods
|
||||
|
||||
- **`email/`**: Email functionality
|
||||
- `templates/`: Email templates
|
||||
- `sender.go`: Email sending service
|
||||
|
||||
- **`scheduler/`**: Job scheduling and execution
|
||||
- `cron.go`: Cron-based job scheduler
|
||||
- `executor.go`: Transfer job executor
|
||||
- `queue.go`: Job queue management
|
||||
|
||||
- **`web/`**: Web interface
|
||||
- `handlers/`: Web request handlers
|
||||
- `middleware/`: Web middleware
|
||||
- `routes.go`: Web route definitions
|
||||
|
||||
#### `components/`
|
||||
|
||||
Contains [templ](https://github.com/a-h/templ) components that define the UI. Templ is a Go HTML templating library that provides type-safe templates.
|
||||
|
||||
```
|
||||
components/
|
||||
├── layouts/ # Page layouts
|
||||
├── partials/ # Reusable UI components
|
||||
├── pages/ # Page templates
|
||||
│ ├── dashboard/
|
||||
│ ├── transfers/
|
||||
│ ├── connections/
|
||||
│ ├── schedules/
|
||||
│ └── admin/
|
||||
└── htmx/ # HTMX-specific components
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
The frontend uses a combination of Tailwind CSS for styling and HTMX for dynamic interactions.
|
||||
|
||||
#### `static/`
|
||||
|
||||
Contains static assets for the web interface:
|
||||
|
||||
- **`css/`**: CSS files
|
||||
- `main.css`: Main stylesheet (compiled from Tailwind)
|
||||
|
||||
- **`js/`**: JavaScript files
|
||||
- `htmx.min.js`: HTMX library
|
||||
- `alpine.min.js`: Alpine.js for lightweight interactivity
|
||||
- `app.js`: Application-specific JavaScript
|
||||
|
||||
- **`img/`**: Images and icons
|
||||
|
||||
## Build System
|
||||
|
||||
GoMFT uses several tools to build and bundle the application:
|
||||
|
||||
- **Go Build**: Compiles the Go code
|
||||
- **Templ**: Compiles templ templates to Go code
|
||||
- **esbuild**: Bundles JavaScript files
|
||||
- **Tailwind CSS**: Compiles CSS
|
||||
|
||||
The build process is orchestrated by a combination of Go commands and npm scripts defined in `package.json`.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- **`.air.toml`**: Configuration for Air, a live reload tool for Go
|
||||
- **`.env.example`**: Example environment variables configuration
|
||||
- **`go.mod`**: Go module definition
|
||||
- **`go.sum`**: Go module checksums
|
||||
- **`package.json`**: npm package definition for frontend dependencies
|
||||
- **`Dockerfile`**: Docker container definition
|
||||
- **`docker-compose.yaml`**: Docker Compose configuration
|
||||
|
||||
## Database Structure
|
||||
|
||||
GoMFT uses GORM (Go Object Relational Mapper) with SQLite as the default database. The main database models include:
|
||||
|
||||
- **`User`**: User account information
|
||||
- **`Role`**: User roles for RBAC
|
||||
- **`Permission`**: Individual permissions
|
||||
- **`Connection`**: File transfer connection configurations
|
||||
- **`Transfer`**: Transfer definitions
|
||||
- **`Schedule`**: Transfer schedules
|
||||
- **`History`**: Transfer execution history
|
||||
- **`Setting`**: Application settings
|
||||
|
||||
## API Structure
|
||||
|
||||
The REST API follows a RESTful design with these main endpoints:
|
||||
|
||||
- **`/api/auth`**: Authentication endpoints
|
||||
- **`/api/users`**: User management
|
||||
- **`/api/connections`**: Connection management
|
||||
- **`/api/transfers`**: Transfer management
|
||||
- **`/api/schedules`**: Schedule management
|
||||
- **`/api/history`**: Transfer history
|
||||
|
||||
Each endpoint typically supports standard CRUD operations.
|
||||
|
||||
## Web Routes
|
||||
|
||||
The web interface is organized around these main routes:
|
||||
|
||||
- **`/`**: Dashboard
|
||||
- **`/connections`**: Connection management
|
||||
- **`/transfers`**: Transfer management
|
||||
- **`/schedules`**: Schedule management
|
||||
- **`/history`**: Transfer history
|
||||
- **`/admin`**: Administrative functions
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
The authentication flow in GoMFT works like this:
|
||||
|
||||
1. User submits credentials via the login form or API
|
||||
2. Credentials are validated against the configured authentication provider(s)
|
||||
3. On success, a session is created for web users or a JWT token is issued for API users
|
||||
4. The user's permissions are loaded based on their role
|
||||
5. Requests are then authenticated via session cookie or JWT token
|
||||
|
||||
## Transfer Execution Flow
|
||||
|
||||
The transfer execution flow is as follows:
|
||||
|
||||
1. Transfer job is initiated (manually or via scheduler)
|
||||
2. Job is added to the execution queue
|
||||
3. Executor picks up the job and prepares the transfer
|
||||
4. rclone is invoked with the appropriate parameters
|
||||
5. Progress is monitored and logged
|
||||
6. Results are recorded in the history
|
||||
7. Notifications are sent if configured
|
||||
|
||||
## Testing Structure
|
||||
|
||||
GoMFT includes several types of tests:
|
||||
|
||||
- **Unit Tests**: Test individual functions and methods
|
||||
- **Integration Tests**: Test interactions between components
|
||||
- **API Tests**: Test API endpoints
|
||||
- **End-to-End Tests**: Test complete user flows
|
||||
|
||||
Tests are organized alongside the code they're testing, following Go conventions.
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation is provided in several formats:
|
||||
|
||||
- **Code Comments**: Go doc comments for packages and functions
|
||||
- **API Documentation**: OpenAPI/Swagger documentation for the REST API
|
||||
- **User Documentation**: User guides and tutorials (this documentation site)
|
||||
- **README**: Project overview and quick start instructions
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Release Process
|
||||
---
|
||||
|
||||
# Release Process
|
||||
|
||||
This document outlines the process for creating and publishing new releases of GoMFT.
|
||||
|
||||
## Version Numbering
|
||||
|
||||
GoMFT follows [Semantic Versioning](https://semver.org/) (SemVer) for version numbering:
|
||||
|
||||
- **Major version** (X.0.0): Incompatible API changes or significant architectural changes
|
||||
- **Minor version** (0.X.0): New features added in a backward-compatible manner
|
||||
- **Patch version** (0.0.X): Backward-compatible bug fixes and minor improvements
|
||||
|
||||
## Release Cycle
|
||||
|
||||
GoMFT follows a time-based release cycle:
|
||||
|
||||
- **Major releases**: Approximately once per year
|
||||
- **Minor releases**: Every 2-3 months
|
||||
- **Patch releases**: As needed for bug fixes and security updates
|
||||
|
||||
## Release Preparation
|
||||
|
||||
### 1. Feature Freeze
|
||||
|
||||
One week before a planned release:
|
||||
|
||||
- No new features are merged into the main branch
|
||||
- Only bug fixes, documentation updates, and release preparation are allowed
|
||||
- All tests must pass on the main branch
|
||||
|
||||
### 2. Update Documentation
|
||||
|
||||
- Ensure all new features are properly documented
|
||||
- Update the changelog with all changes since the last release
|
||||
- Review and update installation and upgrade instructions
|
||||
|
||||
### 3. Version Update
|
||||
|
||||
Update version numbers in:
|
||||
|
||||
- `VERSION` file in the project root
|
||||
- `package.json` for frontend dependencies
|
||||
- `internal/version/version.go` for the Go application
|
||||
|
||||
### 4. Create Release Branch
|
||||
|
||||
For minor and major releases, create a release branch:
|
||||
|
||||
```bash
|
||||
git checkout -b release/vX.Y.Z
|
||||
```
|
||||
|
||||
This branch will be used for final testing and preparation.
|
||||
|
||||
### 5. Update Changelog
|
||||
|
||||
Update the `CHANGELOG.md` file with all changes since the last release:
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
## [X.Y.Z] - YYYY-MM-DD
|
||||
|
||||
### Added
|
||||
- New feature 1
|
||||
- New feature 2
|
||||
|
||||
### Changed
|
||||
- Change 1
|
||||
- Change 2
|
||||
|
||||
### Fixed
|
||||
- Bug fix 1
|
||||
- Bug fix 2
|
||||
|
||||
### Security
|
||||
- Security fix 1
|
||||
```
|
||||
|
||||
## Release Process
|
||||
|
||||
### 1. Final Testing
|
||||
|
||||
Perform the following tests on the release branch:
|
||||
|
||||
- Run the full test suite
|
||||
- Test installation from scratch
|
||||
- Test upgrading from the previous version
|
||||
- Test all major features manually
|
||||
- Test on different platforms (Linux, macOS, Windows)
|
||||
|
||||
### 2. Create Release Commit
|
||||
|
||||
Once testing is complete, commit the version updates:
|
||||
|
||||
```bash
|
||||
git add VERSION package.json internal/version/version.go CHANGELOG.md
|
||||
git commit -m "Release vX.Y.Z"
|
||||
```
|
||||
|
||||
### 3. Tag the Release
|
||||
|
||||
Create an annotated Git tag for the release:
|
||||
|
||||
```bash
|
||||
git tag -a vX.Y.Z -m "Release vX.Y.Z"
|
||||
```
|
||||
|
||||
### 4. Merge to Main
|
||||
|
||||
If using a release branch, merge it back to main:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git merge release/vX.Y.Z
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 5. Push the Tag
|
||||
|
||||
Push the tag to trigger the CI/CD release pipeline:
|
||||
|
||||
```bash
|
||||
git push origin vX.Y.Z
|
||||
```
|
||||
|
||||
## Release Artifacts
|
||||
|
||||
The CI/CD pipeline automatically builds the following artifacts upon tagging:
|
||||
|
||||
1. **Docker Images**:
|
||||
- `gomft/gomft:vX.Y.Z` - Specific version
|
||||
- `gomft/gomft:latest` - Updated for stable releases only
|
||||
|
||||
2. **Binary Distributions**:
|
||||
- Linux (amd64, arm64)
|
||||
- macOS (amd64, arm64)
|
||||
- Windows (amd64)
|
||||
|
||||
3. **Documentation**:
|
||||
- Updated documentation website with the new version
|
||||
|
||||
## Post-Release Tasks
|
||||
|
||||
### 1. Create GitHub Release
|
||||
|
||||
Create a new release on GitHub:
|
||||
|
||||
1. Navigate to the repository's "Releases" page
|
||||
2. Click "Draft a new release"
|
||||
3. Select the tag you just pushed
|
||||
4. Title the release "GoMFT vX.Y.Z"
|
||||
5. Copy the changelog entry for this version
|
||||
6. Attach the built artifacts
|
||||
7. Publish the release
|
||||
|
||||
### 2. Announce the Release
|
||||
|
||||
Announce the new release through:
|
||||
|
||||
- Project website
|
||||
- GitHub Discussions
|
||||
- Relevant community forums or mailing lists
|
||||
|
||||
### 3. Update Demo Environment
|
||||
|
||||
Update the demo/staging environment to the new version to showcase the latest features.
|
||||
|
||||
### 4. Version Bump for Development
|
||||
|
||||
Create a commit on the main branch that bumps the version to the next anticipated version with a `-dev` suffix:
|
||||
|
||||
```bash
|
||||
# Update versions in files to X.Y.(Z+1)-dev
|
||||
git add VERSION package.json internal/version/version.go
|
||||
git commit -m "Bump version to vX.Y.(Z+1)-dev"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Hotfix Releases
|
||||
|
||||
For critical issues that need immediate fixes:
|
||||
|
||||
1. Create a hotfix branch from the release tag:
|
||||
|
||||
```bash
|
||||
git checkout -b hotfix/vX.Y.(Z+1) vX.Y.Z
|
||||
```
|
||||
|
||||
2. Make the necessary fixes
|
||||
|
||||
3. Update version numbers and changelog
|
||||
|
||||
4. Follow the standard release process from the "Final Testing" step
|
||||
|
||||
## Long-Term Support (LTS)
|
||||
|
||||
- Major versions may be designated as LTS releases
|
||||
- LTS releases receive security updates and critical bug fixes for 12 months after the next major version is released
|
||||
- Only the most recent major version receives new features
|
||||
|
||||
## Release Checklist
|
||||
|
||||
Use this checklist for each release:
|
||||
|
||||
- [ ] All tests pass on the main branch
|
||||
- [ ] Documentation is up-to-date
|
||||
- [ ] CHANGELOG.md is updated
|
||||
- [ ] Version numbers are updated in all files
|
||||
- [ ] Release branch created (for minor/major versions)
|
||||
- [ ] Final testing completed successfully
|
||||
- [ ] Release committed and tagged
|
||||
- [ ] Tag pushed to trigger build pipeline
|
||||
- [ ] GitHub release created with changelog and artifacts
|
||||
- [ ] Release announced to the community
|
||||
- [ ] Demo environment updated
|
||||
- [ ] Development version bumped on main branch
|
||||
@@ -0,0 +1,170 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Configuration
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
GoMFT can be customized through environment variables. This document provides a complete list of configuration options available in GoMFT.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Environment variables are the primary way to configure GoMFT, especially when running in Docker. These variables can be set in your Docker Compose file, `.env` file, or directly in your system environment.
|
||||
|
||||
### Core Configuration
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| SERVER_ADDRESS | Server address and port | :8080 | `SERVER_ADDRESS=:9000` |
|
||||
| DATA_DIR | Main data directory | ./data | `DATA_DIR=/app/data` |
|
||||
| BACKUP_DIR | Directory for backups | ./backups | `BACKUP_DIR=/app/backups` |
|
||||
| JWT_SECRET | Secret for JWT tokens | change_this_to_a_secure_random_string | `JWT_SECRET=your-secure-secret-key` |
|
||||
| BASE_URL | Base URL for GoMFT (used in email links) | http://localhost:8080 | `BASE_URL=https://gomft.example.com` |
|
||||
| SKIP_SSL_VERIFY | Skip SSL verification for outgoing webhooks/notifications | false | `SKIP_SSL_VERIFY=false` |
|
||||
|
||||
### Authentication Configuration
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| TOTP_ENCRYPTION_KEY | Encryption key for TOTP secrets | this-is-a-dev-key-not-for-production! | `TOTP_ENCRYPTION_KEY=your-secure-key` |
|
||||
| PUID | User ID to run as (Docker only) | | `PUID=1000` |
|
||||
| PGID | Group ID to run as (Docker only) | | `PGID=1000` |
|
||||
|
||||
### Email Configuration
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| EMAIL_ENABLED | Enable email functionality | false | `EMAIL_ENABLED=true` |
|
||||
| EMAIL_HOST | SMTP server hostname | smtp.example.com | `EMAIL_HOST=smtp.gmail.com` |
|
||||
| EMAIL_PORT | SMTP server port | 587 | `EMAIL_PORT=587` |
|
||||
| EMAIL_USERNAME | SMTP username | user@example.com | `EMAIL_USERNAME=your-email@example.com` |
|
||||
| EMAIL_PASSWORD | SMTP password | your-password | `EMAIL_PASSWORD=your-smtp-password` |
|
||||
| EMAIL_FROM_EMAIL | From email address | gomft@example.com | `EMAIL_FROM_EMAIL=gomft@example.com` |
|
||||
| EMAIL_FROM_NAME | From name | GoMFT | `EMAIL_FROM_NAME=GoMFT Notifications` |
|
||||
| EMAIL_REPLY_TO | Reply-to email address | | `EMAIL_REPLY_TO=support@example.com` |
|
||||
| EMAIL_ENABLE_TLS | Use TLS for SMTP connection | true | `EMAIL_ENABLE_TLS=true` |
|
||||
| EMAIL_REQUIRE_AUTH | Require authentication for SMTP | true | `EMAIL_REQUIRE_AUTH=true` |
|
||||
|
||||
### OAuth Configuration (Optional)
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| GOOGLE_CLIENT_ID | Google OAuth client ID | | `GOOGLE_CLIENT_ID=your-client-id` |
|
||||
| GOOGLE_CLIENT_SECRET | Google OAuth client secret | | `GOOGLE_CLIENT_SECRET=your-client-secret` |
|
||||
|
||||
## Configuration File
|
||||
|
||||
In addition to setting environment variables directly, GoMFT can also be configured using a `.env` file. This file should be placed in the root directory of your GoMFT installation.
|
||||
|
||||
Example `.env` file:
|
||||
|
||||
```
|
||||
# Server Configuration
|
||||
SERVER_ADDRESS=:8080
|
||||
DATA_DIR=./data
|
||||
BACKUP_DIR=./backups
|
||||
JWT_SECRET=change_this_to_a_secure_random_string
|
||||
BASE_URL=http://localhost:8080
|
||||
SKIP_SSL_VERIFY=false
|
||||
|
||||
# Two-Factor Authentication configuration
|
||||
TOTP_ENCRYPTION_KEY=this-is-a-dev-key-not-for-production!
|
||||
|
||||
# OAuth Configuration (optional)
|
||||
# GOOGLE_CLIENT_ID=your_google_client_id
|
||||
# GOOGLE_CLIENT_SECRET=your_google_client_secret
|
||||
|
||||
# Email Configuration
|
||||
EMAIL_ENABLED=true
|
||||
EMAIL_HOST=smtp.example.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_FROM_EMAIL=gomft@example.com
|
||||
EMAIL_FROM_NAME=GoMFT
|
||||
EMAIL_REPLY_TO=
|
||||
EMAIL_ENABLE_TLS=true
|
||||
EMAIL_REQUIRE_AUTH=true
|
||||
EMAIL_USERNAME=your-email@example.com
|
||||
EMAIL_PASSWORD=your-smtp-password
|
||||
```
|
||||
|
||||
## Priority Order
|
||||
|
||||
GoMFT uses the following priority order for configuration:
|
||||
|
||||
1. Environment variables set directly
|
||||
2. Variables in the `.env` file
|
||||
3. Default values
|
||||
|
||||
This means that environment variables set directly will override settings in the `.env` file, which in turn override the default values.
|
||||
|
||||
## Docker Configuration
|
||||
|
||||
When running GoMFT in Docker, you can configure the application in several ways:
|
||||
|
||||
### Using Environment Variables
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v /path/to/data:/app/data \
|
||||
-v /path/to/backups:/app/backups \
|
||||
-e SERVER_ADDRESS=:8080 \
|
||||
-e JWT_SECRET=your-secure-secret \
|
||||
-e EMAIL_ENABLED=true \
|
||||
-e EMAIL_HOST=smtp.example.com \
|
||||
-e PUID=1000 \
|
||||
-e PGID=1000 \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
### Using .env File
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v /path/to/data:/app/data \
|
||||
-v /path/to/backups:/app/backups \
|
||||
-v /path/to/.env:/app/.env \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
### Docker Compose Example
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
- ./.env:/app/.env # Mount .env file (optional)
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
## Applying Configuration Changes
|
||||
|
||||
Most configuration changes require a restart of the GoMFT service to take effect. After modifying environment variables or the `.env` file, restart your container or service:
|
||||
|
||||
```bash
|
||||
# For Docker
|
||||
docker restart gomft
|
||||
|
||||
# For Docker Compose
|
||||
docker-compose restart gomft
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Docker Deployment](/docs/getting-started/docker) - Advanced Docker deployment options
|
||||
- [Non-Root Operation](/docs/security/non-root) - Running GoMFT as a non-root user
|
||||
- [Best Practices](/docs/security/best-practices) - Security best practices
|
||||
@@ -0,0 +1,348 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Docker Deployment
|
||||
---
|
||||
|
||||
# Docker Deployment Guide
|
||||
|
||||
This guide provides detailed instructions for deploying GoMFT using Docker and Docker Compose, including advanced configuration options and best practices.
|
||||
|
||||
## Docker Image Information
|
||||
|
||||
GoMFT is available as a Docker image on Docker Hub:
|
||||
|
||||
- **Image Name**: `starfleetcptn/gomft`
|
||||
- **Tags**:
|
||||
- `latest` - Latest stable release
|
||||
- `edge` - Latest development build
|
||||
- `v0.1.0`, `v0.2.0`, etc. - Specific version releases
|
||||
|
||||
## Basic Docker Run Command
|
||||
|
||||
The simplest way to run GoMFT with Docker:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-v $(pwd)/backups:/app/backups \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
## Docker Compose Setup
|
||||
|
||||
For a more complete and production-ready setup, use Docker Compose:
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
environment:
|
||||
- TZ=UTC
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
Save this to a file named `docker-compose.yml` and run:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Persisting Data
|
||||
|
||||
GoMFT stores data in specific directories that should be mounted as volumes:
|
||||
|
||||
- **/app/data**: Contains the SQLite database, rclone configurations, and logs
|
||||
- **/app/backups**: Contains database backups
|
||||
|
||||
Example with more specific volume mapping:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./data/db:/app/data/db # Database files
|
||||
- ./data/configs:/app/data/configs # Rclone config files
|
||||
- ./data/logs:/app/data/logs # Log files
|
||||
- ./backups:/app/backups # Backup files
|
||||
```
|
||||
|
||||
## File Transfer Volumes
|
||||
|
||||
In addition to the application data, you'll need to mount volumes for the files you want to transfer. These volumes provide GoMFT access to your source files and destination directories.
|
||||
|
||||
### Common File Volume Mounts
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
# Application data volumes
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
|
||||
# File transfer volumes
|
||||
- /path/to/source/files:/sftp/files # Source files for transfer
|
||||
- /path/to/destination:/mft/destination # Destination for transferred files
|
||||
- /path/to/temp:/mft/temp # Temporary processing directory
|
||||
```
|
||||
|
||||
### Docker Run Example with File Volumes
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-v $(pwd)/backups:/app/backups \
|
||||
-v /path/to/source/files:/sftp/files \
|
||||
-v /path/to/destination:/mft/destination \
|
||||
-v /path/to/temp:/mft/temp \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
### Docker Compose Example with File Volumes
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
# Application data
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
|
||||
# File transfer directories
|
||||
- ./source_files:/sftp/files
|
||||
- ./destination:/mft/destination
|
||||
- ./temp:/mft/temp
|
||||
environment:
|
||||
- TZ=UTC
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
### Volume Permissions
|
||||
|
||||
When mounting file volumes, ensure the container has appropriate permissions to access these directories:
|
||||
|
||||
1. If using `PUID` and `PGID` environment variables:
|
||||
```bash
|
||||
# Set correct ownership on host directories
|
||||
chown -R 1000:1000 /path/to/source/files
|
||||
chown -R 1000:1000 /path/to/destination
|
||||
chown -R 1000:1000 /path/to/temp
|
||||
```
|
||||
|
||||
2. Or set appropriate permissions:
|
||||
```bash
|
||||
# Make directories accessible to the container
|
||||
chmod -R 755 /path/to/source/files
|
||||
chmod -R 755 /path/to/destination
|
||||
chmod -R 755 /path/to/temp
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
GoMFT can be configured using environment variables:
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PORT=8080 # Web UI port
|
||||
- BASE_URL=https://gomft.example.com # Base URL for email links
|
||||
- TZ=America/New_York # Timezone
|
||||
```
|
||||
|
||||
### Data Directory Configuration
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- DATA_DIR=/app/data # Main data directory
|
||||
- LOGS_DIR=/app/data/logs # Logs directory
|
||||
- BACKUP_DIR=/app/backups # Backup directory
|
||||
```
|
||||
|
||||
### Email Notification Configuration
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- EMAIL_ENABLED=true # Enable email notifications
|
||||
- EMAIL_HOST=smtp.example.com # SMTP server host
|
||||
- EMAIL_PORT=587 # SMTP server port
|
||||
- EMAIL_USER=user@example.com # SMTP username
|
||||
- EMAIL_PASSWORD=password # SMTP password
|
||||
- EMAIL_FROM=gomft@example.com # From address for emails
|
||||
```
|
||||
|
||||
### Security Configuration
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- JWT_SECRET=your-secret-key # Secret for JWT tokens
|
||||
- ENCRYPT_KEY=32-char-key # Key for encrypting sensitive data
|
||||
```
|
||||
|
||||
## Running as Non-Root User
|
||||
|
||||
For enhanced security, run GoMFT as a non-root user:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PUID=1000 # User ID to run as
|
||||
- PGID=1000 # Group ID to run as
|
||||
```
|
||||
|
||||
Make sure your mounted volumes have the appropriate permissions for this user.
|
||||
|
||||
## Exposing GoMFT Behind a Reverse Proxy
|
||||
|
||||
It's recommended to run GoMFT behind a reverse proxy like Nginx or Traefik for SSL termination and security.
|
||||
|
||||
### Nginx Example
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name gomft.example.com;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name gomft.example.com;
|
||||
|
||||
ssl_certificate /etc/nginx/ssl/cert.pem;
|
||||
ssl_certificate_key /etc/nginx/ssl/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://gomft:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Docker Compose with Traefik Example
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
traefik:
|
||||
image: traefik:v2.5
|
||||
command:
|
||||
- "--providers.docker=true"
|
||||
- "--providers.docker.exposedbydefault=false"
|
||||
- "--entrypoints.web.address=:80"
|
||||
- "--entrypoints.websecure.address=:443"
|
||||
- "--certificatesresolvers.myresolver.acme.tlschallenge=true"
|
||||
- "--certificatesresolvers.myresolver.acme.email=your@email.com"
|
||||
- "--certificatesresolvers.myresolver.acme.storage=/acme.json"
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- ./acme.json:/acme.json
|
||||
restart: unless-stopped
|
||||
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- BASE_URL=https://gomft.example.com
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.gomft.rule=Host(`gomft.example.com`)"
|
||||
- "traefik.http.routers.gomft.entrypoints=websecure"
|
||||
- "traefik.http.routers.gomft.tls.certresolver=myresolver"
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
You can configure a health check to monitor the container's health:
|
||||
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
||||
interval: 1m
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
```
|
||||
|
||||
## Resource Limits
|
||||
|
||||
Set resource limits to prevent the container from consuming too many resources:
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1'
|
||||
memory: 1G
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
memory: 512M
|
||||
```
|
||||
|
||||
## Logging Configuration
|
||||
|
||||
Configure container logging:
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
driver: "json-file"
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
```
|
||||
|
||||
## Troubleshooting Docker Deployment
|
||||
|
||||
If you encounter issues with your Docker deployment:
|
||||
|
||||
1. Check container logs:
|
||||
```
|
||||
docker logs gomft
|
||||
```
|
||||
|
||||
2. Check container status:
|
||||
```
|
||||
docker ps -a | grep gomft
|
||||
```
|
||||
|
||||
3. Verify volume permissions:
|
||||
```
|
||||
ls -la ./data
|
||||
```
|
||||
|
||||
4. Check container environment:
|
||||
```
|
||||
docker exec gomft env
|
||||
```
|
||||
|
||||
5. Inspect the container:
|
||||
```
|
||||
docker inspect gomft
|
||||
```
|
||||
|
||||
For more help, refer to the [GitHub repository](https://github.com/StarFleetCPTN/GoMFT) or open an issue.
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Installation
|
||||
---
|
||||
|
||||
# Installing GoMFT
|
||||
|
||||
GoMFT can be installed using Docker (recommended) or through a traditional installation. This guide covers both methods.
|
||||
|
||||
## System Requirements
|
||||
|
||||
- **CPU**: 1+ cores (2+ recommended for production)
|
||||
- **RAM**: 512MB minimum (1GB+ recommended for production)
|
||||
- **Disk Space**: 100MB for the application plus space for your transfer data and logs
|
||||
- **Operating System**: Linux, macOS, or Windows with Docker support
|
||||
|
||||
## Docker Installation (Recommended)
|
||||
|
||||
The easiest way to deploy GoMFT is using Docker. This method handles all dependencies and provides an isolated environment.
|
||||
|
||||
### Using Docker Run
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v /path/to/data:/app/data \
|
||||
-v /path/to/backups:/app/backups \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
Replace `/path/to/data` and `/path/to/backups` with your desired local paths for persistent storage.
|
||||
|
||||
### Using Docker Compose
|
||||
|
||||
Create a `docker-compose.yaml` file:
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
environment:
|
||||
- TZ=UTC
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
You can customize your GoMFT installation using environment variables:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TZ=America/New_York
|
||||
- PORT=8080
|
||||
- DATA_DIR=/app/data
|
||||
- BACKUP_DIR=/app/backups
|
||||
- LOGS_DIR=/app/data/logs
|
||||
- EMAIL_ENABLED=false
|
||||
- BASE_URL=http://localhost:8080
|
||||
```
|
||||
|
||||
See the [Configuration](/docs/getting-started/configuration) section for a complete list of environment variables.
|
||||
|
||||
### File Volume Mounts
|
||||
|
||||
When running GoMFT in Docker, you'll need to mount volumes to provide access to the files you want to transfer. Here are common volume mount scenarios:
|
||||
|
||||
#### For SFTP/FTP Source Files
|
||||
```bash
|
||||
-v /path/to/local/files:/sftp/files
|
||||
```
|
||||
|
||||
#### For Destination Directories
|
||||
```bash
|
||||
-v /path/to/destination:/mft/destination
|
||||
```
|
||||
|
||||
#### For Processing Temporary Files
|
||||
```bash
|
||||
-v /path/to/temp:/mft/temp
|
||||
```
|
||||
|
||||
Example using Docker Run with file volumes:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name gomft \
|
||||
-p 8080:8080 \
|
||||
-v /path/to/data:/app/data \
|
||||
-v /path/to/backups:/app/backups \
|
||||
-v /path/to/local/files:/sftp/files \
|
||||
-v /path/to/destination:/mft/destination \
|
||||
starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
Example Docker Compose configuration with file volumes:
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
ports:
|
||||
- "8080:8080"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
- ./source_files:/sftp/files
|
||||
- ./destination:/mft/destination
|
||||
- ./temp:/mft/temp
|
||||
environment:
|
||||
- TZ=UTC
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
> **Note**: Ensure the container has appropriate permissions to access the mounted directories. You may need to adjust host-side permissions accordingly.
|
||||
|
||||
## Traditional Installation
|
||||
|
||||
For environments where Docker is not available or preferred, you can install GoMFT directly.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Go 1.20 or later
|
||||
- Node.js 18 or later
|
||||
- gcc (for building SQLite dependencies)
|
||||
|
||||
### Building from Source
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/StarFleetCPTN/GoMFT.git
|
||||
cd GoMFT
|
||||
```
|
||||
|
||||
2. Install Node.js dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Build the frontend assets:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
4. Build the Go application:
|
||||
|
||||
```bash
|
||||
go build -o gomft
|
||||
```
|
||||
|
||||
5. Run the application:
|
||||
|
||||
```bash
|
||||
./gomft
|
||||
```
|
||||
|
||||
## Verifying the Installation
|
||||
|
||||
After installation, access the GoMFT web interface by navigating to:
|
||||
|
||||
```
|
||||
http://localhost:8080
|
||||
```
|
||||
|
||||
The default login credentials are:
|
||||
|
||||
- **Username**: admin
|
||||
- **Password**: admin
|
||||
|
||||
**Important**: Change the default password immediately after the first login for security reasons.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once GoMFT is installed, proceed to the [Quick Start](/docs/getting-started/quick-start) guide to begin configuring your file transfers.
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Quick Start
|
||||
---
|
||||
|
||||
# GoMFT Quick Start Guide
|
||||
|
||||
This guide will help you get up and running with GoMFT quickly. We'll cover logging in, creating your first connection configuration, and setting up a file transfer.
|
||||
|
||||
## Accessing the Web Interface
|
||||
|
||||
After installation, access the GoMFT web interface at `http://your-server:8080` (or the appropriate port if you've modified it).
|
||||
|
||||
1. Log in with the default credentials:
|
||||
- **Username**: admin@example.com
|
||||
- **Password**: admin
|
||||
|
||||
## Initial Dashboard
|
||||
|
||||
The dashboard provides an overview of:
|
||||
- Recent transfer jobs
|
||||
- Upcoming scheduled transfers
|
||||
- System status
|
||||
- Quick action buttons
|
||||
|
||||
|
||||
|
||||
## Creating Your First Transfer Configuration
|
||||
|
||||
1. Navigate to **Transfer Configurations** in the sidebar menu
|
||||
2. Click **+ New Configuration**
|
||||
3. Configure the transfer:
|
||||
- Select source and destination configurations
|
||||
- Specify source and destination paths
|
||||
- Choose the transfer type (Copy, Sync, Move, etc.)
|
||||
- Configure transfer options (file filtering, bandwidth limits, etc.)
|
||||
4. Click **Save Transfer**
|
||||
|
||||
|
||||
|
||||
## Create Your First Scheduled Job
|
||||
1. Naviagate to **Scheduled Jobs** in the sidebar menu
|
||||
2. Click **+ New Job**
|
||||
3. Configure the job:
|
||||
- Specifiy schedule
|
||||
- Select Job(s) to run this can be 1 or more
|
||||
- Change job run order if needed
|
||||
|
||||
## Running a Transfer
|
||||
|
||||
Once you've created a transfer configuration, you can:
|
||||
|
||||
### Run On-Demand
|
||||
|
||||
1. Navigate to **Secheduled Jobs**
|
||||
2. Find your transfer in the list
|
||||
3. Click the **Run Now** button
|
||||
4. The transfer will execute immediately
|
||||
|
||||
### Schedule a Transfer
|
||||
|
||||
1. Navigate to **Schedules**
|
||||
2. Click **Create New Schedule**
|
||||
3. Select your transfer configuration
|
||||
4. Set the schedule using cron syntax or the schedule builder
|
||||
5. Set additional options (timeout, max retries, etc.)
|
||||
6. Click **Save Schedule**
|
||||
|
||||
## Monitoring Transfers
|
||||
|
||||
1. Navigate to **Transfer History** to view all past and ongoing transfers
|
||||
2. Click on a specific transfer to view detailed information:
|
||||
- Transfer status
|
||||
- Start and end times
|
||||
- Files transferred
|
||||
- Bytes transferred
|
||||
- Errors (if any)
|
||||
- Transfer log
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you've set up your first transfer, explore these additional features:
|
||||
|
||||
- [Docker Deployment](/docs/getting-started/docker) - For containerized deployment
|
||||
- [Traditional Installation](/docs/getting-started/traditional) - For non-Docker environments
|
||||
- [Transfer Concepts](/docs/core-concepts/transfers) - Learn more about transfer operations
|
||||
- [Scheduling](/docs/core-concepts/schedules) - Advanced scheduling options
|
||||
- [Monitoring](/docs/core-concepts/monitoring) - Advanced monitoring capabilities
|
||||
@@ -0,0 +1,325 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Traditional Installation
|
||||
---
|
||||
|
||||
# Traditional Installation Guide
|
||||
|
||||
This guide covers installing GoMFT directly on your system without using Docker. This approach is useful for environments where containers aren't available or when you need more direct control over the installation.
|
||||
|
||||
## System Requirements
|
||||
|
||||
- **Operating System**: Linux, macOS, or Windows
|
||||
- **Go**: Version 1.20 or later
|
||||
- **Node.js**: Version 18 or later
|
||||
- **Build Tools**: gcc and related build tools (for SQLite compilation)
|
||||
|
||||
## Prerequisites Installation
|
||||
|
||||
### On Debian/Ubuntu Linux
|
||||
|
||||
```bash
|
||||
# Install Go
|
||||
wget https://go.dev/dl/go1.20.linux-amd64.tar.gz
|
||||
sudo tar -C /usr/local -xzf go1.20.linux-amd64.tar.gz
|
||||
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
|
||||
source ~/.profile
|
||||
|
||||
# Install Node.js
|
||||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Install build tools
|
||||
sudo apt-get install -y build-essential
|
||||
```
|
||||
|
||||
### On macOS
|
||||
|
||||
```bash
|
||||
# Using Homebrew
|
||||
brew install go
|
||||
brew install node
|
||||
brew install gcc
|
||||
```
|
||||
|
||||
### On Windows
|
||||
|
||||
1. Install Go from [https://golang.org/dl/](https://golang.org/dl/)
|
||||
2. Install Node.js from [https://nodejs.org/](https://nodejs.org/)
|
||||
3. Install Build Tools for Visual Studio
|
||||
|
||||
## Building GoMFT from Source
|
||||
|
||||
1. Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/StarFleetCPTN/GoMFT.git
|
||||
cd GoMFT
|
||||
```
|
||||
|
||||
2. Install Node.js dependencies and build the frontend:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
3. Compile the Go application:
|
||||
|
||||
```bash
|
||||
go build -o gomft main.go
|
||||
```
|
||||
|
||||
## Installation Options
|
||||
|
||||
### Option 1: Run Directly
|
||||
|
||||
After building, you can run the application directly:
|
||||
|
||||
```bash
|
||||
./gomft
|
||||
```
|
||||
|
||||
### Option 2: Install as a System Service
|
||||
|
||||
#### On Linux (systemd)
|
||||
|
||||
Create a systemd service file:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/gomft.service
|
||||
```
|
||||
|
||||
Add the following content:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=GoMFT - Go Managed File Transfer
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=gomft
|
||||
Group=gomft
|
||||
WorkingDirectory=/opt/gomft
|
||||
ExecStart=/opt/gomft/gomft
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
Environment="PORT=8080"
|
||||
Environment="DATA_DIR=/var/lib/gomft/data"
|
||||
Environment="BACKUP_DIR=/var/lib/gomft/backups"
|
||||
Environment="LOGS_DIR=/var/log/gomft"
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Create a dedicated user and set up directories:
|
||||
|
||||
```bash
|
||||
# Create user
|
||||
sudo useradd -r -s /bin/false gomft
|
||||
|
||||
# Create directories
|
||||
sudo mkdir -p /opt/gomft /var/lib/gomft/data /var/lib/gomft/backups /var/log/gomft
|
||||
|
||||
# Copy application
|
||||
sudo cp -r * /opt/gomft/
|
||||
|
||||
# Set permissions
|
||||
sudo chown -R gomft:gomft /opt/gomft /var/lib/gomft /var/log/gomft
|
||||
```
|
||||
|
||||
Enable and start the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable gomft
|
||||
sudo systemctl start gomft
|
||||
```
|
||||
|
||||
#### On macOS (launchd)
|
||||
|
||||
Create a launchd plist file:
|
||||
|
||||
```bash
|
||||
sudo nano /Library/LaunchDaemons/com.gomft.plist
|
||||
```
|
||||
|
||||
Add the following content:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.gomft</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/usr/local/gomft/gomft</string>
|
||||
</array>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/usr/local/gomft</string>
|
||||
<key>EnvironmentVariables</key>
|
||||
<dict>
|
||||
<key>PORT</key>
|
||||
<string>8080</string>
|
||||
<key>DATA_DIR</key>
|
||||
<string>/var/lib/gomft/data</string>
|
||||
<key>BACKUP_DIR</key>
|
||||
<string>/var/lib/gomft/backups</string>
|
||||
<key>LOGS_DIR</key>
|
||||
<string>/var/log/gomft</string>
|
||||
</dict>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
Set up directories and install:
|
||||
|
||||
```bash
|
||||
# Create directories
|
||||
sudo mkdir -p /usr/local/gomft /var/lib/gomft/data /var/lib/gomft/backups /var/log/gomft
|
||||
|
||||
# Copy application
|
||||
sudo cp -r * /usr/local/gomft/
|
||||
|
||||
# Set permissions
|
||||
sudo chown -R $(whoami):staff /usr/local/gomft /var/lib/gomft /var/log/gomft
|
||||
|
||||
# Load service
|
||||
sudo launchctl load /Library/LaunchDaemons/com.gomft.plist
|
||||
```
|
||||
|
||||
#### On Windows (Windows Service)
|
||||
|
||||
1. Install [NSSM (Non-Sucking Service Manager)](https://nssm.cc/download)
|
||||
2. Open Command Prompt as Administrator
|
||||
3. Create the service:
|
||||
|
||||
```bat
|
||||
nssm install GoMFT C:\path\to\gomft.exe
|
||||
nssm set GoMFT AppDirectory C:\path\to\gomft\directory
|
||||
nssm set GoMFT AppEnvironmentExtra PORT=8080 DATA_DIR=C:\ProgramData\GoMFT\data BACKUP_DIR=C:\ProgramData\GoMFT\backups LOGS_DIR=C:\ProgramData\GoMFT\logs
|
||||
nssm start GoMFT
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file in the application directory or set system environment variables:
|
||||
|
||||
```
|
||||
PORT=8080
|
||||
DATA_DIR=/var/lib/gomft/data
|
||||
BACKUP_DIR=/var/lib/gomft/backups
|
||||
LOGS_DIR=/var/log/gomft
|
||||
BASE_URL=http://localhost:8080
|
||||
EMAIL_ENABLED=false
|
||||
JWT_SECRET=your-secret-key
|
||||
ENCRYPT_KEY=32-character-encryption-key
|
||||
```
|
||||
|
||||
### Web Server Setup
|
||||
|
||||
For production use, it's recommended to run GoMFT behind a web server like Nginx:
|
||||
|
||||
#### Nginx Configuration
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-gomft-server.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Updating GoMFT
|
||||
|
||||
To update a traditionally installed GoMFT:
|
||||
|
||||
1. Stop the service:
|
||||
```bash
|
||||
sudo systemctl stop gomft # For Linux
|
||||
sudo launchctl unload /Library/LaunchDaemons/com.gomft.plist # For macOS
|
||||
nssm stop GoMFT # For Windows
|
||||
```
|
||||
|
||||
2. Back up your data:
|
||||
```bash
|
||||
cp -r /var/lib/gomft/data /var/lib/gomft/data.backup
|
||||
```
|
||||
|
||||
3. Get the latest code:
|
||||
```bash
|
||||
cd /path/to/gomft/source
|
||||
git pull
|
||||
```
|
||||
|
||||
4. Rebuild:
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
go build -o gomft main.go
|
||||
```
|
||||
|
||||
5. Update the installation:
|
||||
```bash
|
||||
sudo cp gomft /opt/gomft/ # For Linux
|
||||
sudo cp gomft /usr/local/gomft/ # For macOS
|
||||
copy gomft.exe C:\path\to\gomft.exe # For Windows
|
||||
```
|
||||
|
||||
6. Restart the service:
|
||||
```bash
|
||||
sudo systemctl start gomft # For Linux
|
||||
sudo launchctl load /Library/LaunchDaemons/com.gomft.plist # For macOS
|
||||
nssm start GoMFT # For Windows
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Permission Errors**:
|
||||
- Check that the user running GoMFT has write permissions to the data, backup, and logs directories.
|
||||
|
||||
2. **Database Errors**:
|
||||
- Ensure the SQLite database path is writeable.
|
||||
- Check database integrity: `sqlite3 /var/lib/gomft/data/gomft.db "PRAGMA integrity_check;"`
|
||||
|
||||
3. **Port Already in Use**:
|
||||
- Change the port in the configuration.
|
||||
- Check what's using port 8080: `sudo lsof -i :8080`
|
||||
|
||||
4. **Missing Dependencies**:
|
||||
- Make sure all required Go and Node.js dependencies are installed.
|
||||
|
||||
### Viewing Logs
|
||||
|
||||
- **Application Logs**: Check `/var/log/gomft/` or your configured logs directory
|
||||
- **System Service Logs**:
|
||||
```bash
|
||||
# For Linux
|
||||
journalctl -u gomft
|
||||
|
||||
# For macOS
|
||||
log show --predicate 'senderImagePath contains "gomft"'
|
||||
|
||||
# For Windows
|
||||
Get-EventLog -LogName Application -Source GoMFT
|
||||
```
|
||||
|
||||
For more help, refer to the [GitHub repository](https://github.com/StarFleetCPTN/GoMFT) or open an issue.
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Features
|
||||
---
|
||||
|
||||
# GoMFT Features
|
||||
|
||||
GoMFT offers a comprehensive set of features that make it a powerful solution for managed file transfers. Here's a detailed breakdown of what GoMFT offers:
|
||||
|
||||
## Core Features
|
||||
|
||||
### Multi-Protocol Support
|
||||
|
||||
GoMFT leverages rclone to support a wide range of storage providers and protocols:
|
||||
|
||||
- **Cloud Storage**: Amazon S3, Google Cloud Storage
|
||||
- **Object Storage**: MinIO, Backblaze B2, Wasabi
|
||||
- **FTP/SFTP**: FTP, FTPS, SFTP servers
|
||||
- **WebDAV**: WebDAV servers and services
|
||||
- **Local Storage**: Local disk, SMB/CIFS shares
|
||||
- **And many more**: Over 40 storage systems supported
|
||||
|
||||
### Intuitive Web Interface
|
||||
|
||||
- **Clean, Modern UI**: Easy-to-use web interface built with Tailwind CSS and HTMX
|
||||
- **Dashboard**: Overview of recent transfers, scheduled jobs, and system status
|
||||
- **Configuration Manager**: Visual interface for creating and editing transfer configurations
|
||||
- **Job Scheduler**: Interface for creating and managing scheduled jobs
|
||||
- **Transfer Logs**: Detailed logs of all transfer operations
|
||||
- **Dark Mode**: Support for light and dark themes
|
||||
|
||||
### Powerful Scheduling
|
||||
|
||||
- **Cron-style Scheduling**: Set up transfers using familiar cron syntax
|
||||
- **Recurring Transfers**: Schedule transfers to run on a regular basis
|
||||
- **One-time Transfers**: Run transfers immediately or at a specific time
|
||||
- **Schedule Grouping**: Organize schedules into logical groups
|
||||
- **Priority Control**: Set priority levels for scheduled tasks
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Transfer Options
|
||||
|
||||
- **Bidirectional Sync**: Synchronize files in both directions
|
||||
- **File Filtering**: Include or exclude files based on patterns
|
||||
- **Bandwidth Limiting**: Restrict bandwidth usage for transfers
|
||||
- **Parallel Transfers**: Configure the number of simultaneous transfers
|
||||
- **Delta Transfers**: Transfer only changed parts of files
|
||||
- **Checksumming**: Verify file integrity during transfers
|
||||
|
||||
### Notification System
|
||||
|
||||
- **Notifications**: Receive alerts when transfers complete or fail
|
||||
- **Custom Templates**: Customize notification content and format
|
||||
- **Notification Rules**: Configure which events trigger notifications
|
||||
- **Notification Providers**: Webhooks, Ntfy, Gotify, Pushover, Pushbullet
|
||||
|
||||
### Admin Tools
|
||||
|
||||
- **User Management**: Create and manage users with different roles
|
||||
- **Role-Based Access Control**: Control access to different parts of the application
|
||||
- **Audit Logging**: Track user actions for security and compliance
|
||||
- **System Monitoring**: Monitor system performance and resource usage
|
||||
- **Database Backup/Restore**: Back up and restore the application database
|
||||
- **Log Viewer**: Browse and search through application logs
|
||||
|
||||
### Security Features
|
||||
|
||||
- **Authentication**: Secure login with optional MFA support
|
||||
- **Encryption**: Encrypt data in transit and at rest
|
||||
- **Secure Credential Storage**: Safely store connection credentials
|
||||
- **Non-Root Container Support**: Run containers as non-root users for enhanced security
|
||||
|
||||
## Integration Capabilities
|
||||
|
||||
- **Docker Support**: Easy deployment with Docker containers
|
||||
- **Docker Compose**: Multi-container deployment using Docker Compose
|
||||
- **Reverse Proxy Compatible**: Works behind reverse proxies like Nginx or Traefik
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Overview
|
||||
---
|
||||
|
||||
# GoMFT Overview
|
||||
|
||||
GoMFT is a modern, web-based managed file transfer solution written in Go. It provides an intuitive interface for setting up, scheduling, and monitoring file transfers across various storage backends.
|
||||
|
||||
## What is GoMFT?
|
||||
|
||||
GoMFT (Go Managed File Transfer) is an open-source file transfer platform that enables reliable, secure, and automated file transfers. Built on top of the powerful [rclone](https://rclone.org/) engine, GoMFT provides a user-friendly web interface that makes it easy to configure and manage complex file transfer operations.
|
||||
|
||||
## Key Benefits
|
||||
|
||||
- **User-Friendly Interface**: Intuitive web UI for configuring and monitoring file transfers
|
||||
- **Multi-Protocol Support**: Transfer files using SFTP, S3, Google Drive, and many more protocols
|
||||
- **Automated Scheduling**: Set up recurring transfers with flexible scheduling options
|
||||
- **Comprehensive Logging**: Detailed logs for troubleshooting and audit purposes
|
||||
- **Notifications**: Get alerts when transfers succeed or fail
|
||||
- **Docker Support**: Easy deployment with Docker containers
|
||||
- **Security**: Role-based access control and secure credential management
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Data Synchronization**: Keep files in sync across different storage systems
|
||||
- **Backup and Archiving**: Automate backup processes to cloud or local storage
|
||||
- **Secure File Exchange**: Transfer files securely between organizations
|
||||
- **Cloud Migration**: Move data between different cloud providers
|
||||
- **Workflow Automation**: Trigger file transfers as part of larger workflows
|
||||
- **Compliance**: Maintain audit logs for regulatory compliance
|
||||
|
||||
GoMFT is designed to be simple to deploy and use, while providing the reliability and features needed for enterprise file transfer needs.
|
||||
|
||||
## Community Support
|
||||
|
||||
Join our Discord community for support, discussions, and updates about GoMFT:
|
||||
|
||||
<a href="https://discord.gg/f9dwtM3j" className="discord-badge">Join Discord Community</a>
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Authentication
|
||||
---
|
||||
|
||||
# Authentication and Authorization
|
||||
|
||||
GoMFT provides robust authentication and authorization mechanisms to ensure secure access to the application and its features. This page explains how to configure and manage authentication in GoMFT.
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
GoMFT supports multiple authentication methods to secure access to the application:
|
||||
|
||||
### Local Authentication
|
||||
|
||||
The default authentication method using GoMFT's built-in user database:
|
||||
|
||||
- **Username/Password**: Traditional username and password authentication
|
||||
- **Password Requirements**: Configurable password complexity rules
|
||||
- **Password Expiration**: Force password changes after a configurable period
|
||||
- **Account Lockout**: Temporarily lock accounts after failed login attempts
|
||||
|
||||
### OAuth/OpenID Connect
|
||||
|
||||
Support for modern identity providers:
|
||||
|
||||
- **Single Sign-On**: Integrate with SSO solutions
|
||||
- **Identity Providers**: Support for popular providers (Google, Microsoft, Okta, etc.)
|
||||
- **JWT Tokens**: Secure token-based authentication
|
||||
- **Automatic Account Provisioning (COMING SOON)**: Create GoMFT accounts based on SSO information
|
||||
|
||||
## Setting Up Authentication
|
||||
|
||||
### Configuring Local Authentication
|
||||
|
||||
Local authentication is enabled by default and requires minimal setup:
|
||||
|
||||
### Configuring OAuth/OpenID Connect
|
||||
|
||||
To set up OAuth or OpenID Connect:
|
||||
|
||||
1. Navigate to **Settingss** > **Authentication Providers**
|
||||
2. Select **OAuth/OIDC** as an authentication method
|
||||
3. Configure provider settings:
|
||||
- Provider URL
|
||||
- Client ID
|
||||
- Client Secret
|
||||
- Scope (e.g., `openid profile email`)
|
||||
- Callback URL
|
||||
4. Set up attribute mappings:
|
||||
- Map provider attributes to GoMFT user properties
|
||||
- Configure role attribute or claim
|
||||
5. Test the configuration
|
||||
|
||||
## Multi-Factor Authentication (MFA)
|
||||
|
||||
GoMFT supports multi-factor authentication for enhanced security:
|
||||
|
||||
### MFA Options
|
||||
|
||||
- **Time-based One-Time Password (TOTP)**: Compatible with apps like Google Authenticator
|
||||
- **Email Verification Codes**: One-time codes sent via email
|
||||
- **Recovery Codes**: Backup codes for emergency access
|
||||
|
||||
### Enabling MFA
|
||||
|
||||
For users to set up MFA:
|
||||
|
||||
1. Log in to GoMFT
|
||||
2. Navigate to **Profile** > **Security Settings**
|
||||
3. Select **Enable Multi-Factor Authentication**
|
||||
4. Choose the MFA method (e.g., TOTP)
|
||||
5. Follow the setup instructions:
|
||||
- For TOTP: Scan QR code with authenticator app
|
||||
- For Email: Verify email address
|
||||
6. Generate and save recovery codes
|
||||
|
||||
## User Management
|
||||
|
||||
### Creating Users
|
||||
|
||||
To create new users:
|
||||
|
||||
1. Navigate to **Administration** > **Users**
|
||||
2. Click **Create New User**
|
||||
3. Fill in the user details:
|
||||
- Username
|
||||
- Email address
|
||||
- Full name
|
||||
- Initial password or send password reset link
|
||||
- Role assignment
|
||||
4. Click **Create Users**
|
||||
|
||||
### Managing User Accounts
|
||||
|
||||
To manage existing users:
|
||||
|
||||
1. Navigate to **Administration** > **Users**
|
||||
2. Find the user in the list
|
||||
3. Available actions:
|
||||
- Edit user details
|
||||
- Change role assignment
|
||||
- Reset password
|
||||
- Enable/disable account
|
||||
- Force MFA enrollment
|
||||
- Delete user
|
||||
|
||||
### User Self-Service
|
||||
|
||||
GoMFT provides self-service features for users:
|
||||
|
||||
- **Profile Management**: Users can update their profile information
|
||||
- **Password Change**: Users can change their password
|
||||
- **MFA Setup**: Users can configure their MFA preferences
|
||||
|
||||
## Role-Based Access Control
|
||||
|
||||
GoMFT implements role-based access control (RBAC) to manage permissions:
|
||||
|
||||
### Default Roles
|
||||
|
||||
- **Administrator**: Full access to all system features
|
||||
- **System**: Can manage transfers and connections but not admin settings
|
||||
- **User**: Basic access to create and manage personal transfers
|
||||
|
||||
### Creating Custom Roles
|
||||
|
||||
To create a custom role:
|
||||
|
||||
1. Navigate to **Administration** > **Roles**
|
||||
2. Click **Create New Role**
|
||||
3. Define the role:
|
||||
- Role name
|
||||
- Description
|
||||
- Permission assignments
|
||||
4. Save the role
|
||||
|
||||
### Permission Categories
|
||||
|
||||
GoMFT organizes permissions into categories:
|
||||
|
||||
- **System Administration**: System-wide settings and maintenance
|
||||
- **User Management**: User and role administration
|
||||
- **Transfer Management**: Creating and managing transfers
|
||||
- **Connection Management**: Creating and managing connections
|
||||
- **Schedule Management**: Managing transfer schedules
|
||||
- **Execution Control**: Running and controlling transfers
|
||||
- **Monitoring**: Viewing logs and reports
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- **Enforce Strong Passwords**: Configure strong password requirements
|
||||
- **Enable MFA**: Require MFA for all users, especially administrators
|
||||
- **Regular Review**: Periodically review user accounts and permissions
|
||||
- **Principle of Least Privilege**: Assign the minimum necessary permissions
|
||||
- **Audit Authentication**: Monitor and audit authentication events
|
||||
- **Secure Configuration**: Properly secure authentication configuration files
|
||||
- **Account Lifecycle**: Implement processes for account creation and termination
|
||||
@@ -0,0 +1,187 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Security Best Practices
|
||||
---
|
||||
|
||||
# Security Best Practices
|
||||
|
||||
This guide provides recommendations for securing your GoMFT installation and maintaining a secure file transfer environment.
|
||||
|
||||
## Installation Security
|
||||
|
||||
### Use Docker Security Features
|
||||
|
||||
When deploying GoMFT with Docker:
|
||||
|
||||
- **Run as Non-Root**: Always run the container as a non-root user (see [Running as Non-Root](/docs/security/non-root))
|
||||
- **Use Read-Only Filesystem**: Mount the filesystem as read-only except for specific data directories
|
||||
- **Limit Capabilities**: Use Docker's `--cap-drop` to limit container capabilities
|
||||
- **Set Resource Limits**: Prevent resource exhaustion with memory and CPU limits
|
||||
- **Use Docker Secrets**: Store sensitive configuration in Docker secrets instead of environment variables
|
||||
|
||||
Example secure docker-compose configuration:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
user: "1000:1000"
|
||||
read_only: true
|
||||
cap_drop:
|
||||
- ALL
|
||||
cap_add:
|
||||
- NET_BIND_SERVICE
|
||||
security_opt:
|
||||
- no-new-privileges:true
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
environment:
|
||||
- TZ=UTC
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1'
|
||||
memory: 1G
|
||||
```
|
||||
|
||||
### Traditional Installation Security
|
||||
|
||||
For traditional installations:
|
||||
|
||||
- **Dedicated User**: Create a dedicated system user for running GoMFT
|
||||
- **Minimal Permissions**: Give the user only the permissions it needs
|
||||
- **Firewall Rules**: Restrict access to only necessary ports
|
||||
- **SELinux/AppArmor**: Use system security modules to limit application scope
|
||||
|
||||
## Network Security
|
||||
|
||||
### Use HTTPS
|
||||
|
||||
Always use HTTPS for the web interface:
|
||||
|
||||
- **Configure TLS**: Use a reverse proxy like Nginx or Traefik for TLS termination
|
||||
- **Strong Ciphers**: Use modern, secure cipher suites
|
||||
- **HSTS**: Enable HTTP Strict Transport Security
|
||||
- **Valid Certificates**: Use trusted certificates from Let's Encrypt or other providers
|
||||
|
||||
### Access Control
|
||||
|
||||
- **IP Restrictions**: Limit access to trusted IP addresses where possible
|
||||
- **VPN Access**: Consider placing GoMFT behind a VPN for additional security
|
||||
- **Firewall Rules**: Configure firewall rules to restrict access to essential ports only
|
||||
|
||||
## Authentication and Authorization
|
||||
|
||||
### Strong Authentication
|
||||
|
||||
- **Password Policy**: Enforce strong password requirements
|
||||
- **MFA**: Enable Multi-Factor Authentication for all users
|
||||
- **Session Management**: Set appropriate session timeouts
|
||||
- **Failed Login Limits**: Implement account lockouts after several failed attempts
|
||||
|
||||
### Role-Based Access Control
|
||||
|
||||
- **Principle of Least Privilege**: Grant users only the permissions they need
|
||||
- **Separation of Duties**: Use roles to separate administrative functions
|
||||
- **Regular Review**: Periodically review user roles and permissions
|
||||
|
||||
## Credential Management
|
||||
|
||||
### Secure Storage
|
||||
|
||||
- **Encrypted Credentials**: Ensure all credentials are encrypted at rest
|
||||
- **Isolated Storage**: Store sensitive credentials in a separate database or secure storage
|
||||
- **Key Rotation**: Regularly rotate encryption keys
|
||||
|
||||
### Credential Practices
|
||||
|
||||
- **Service Accounts**: Use service accounts instead of personal accounts for connections
|
||||
- **Temporary Credentials**: Use temporary credentials where supported (e.g., AWS STS)
|
||||
- **API Keys**: Regularly rotate API keys and access tokens
|
||||
- **Minimal Scope**: Grant credentials the minimum required permissions
|
||||
|
||||
## Transfer Security
|
||||
|
||||
### Secure Protocols
|
||||
|
||||
- **Choose Secure Protocols**: Prefer SFTP, FTPS, or HTTPS over unencrypted protocols
|
||||
- **Disable Legacy Protocols**: Disable insecure protocols like FTP where possible
|
||||
- **Strong Ciphers**: Configure secure cipher suites for encrypted protocols
|
||||
|
||||
### Data Handling
|
||||
|
||||
- **Data Classification**: Classify data by sensitivity and apply appropriate controls
|
||||
- **Data Validation**: Validate files before processing them
|
||||
- **Virus Scanning**: Implement virus scanning for transferred files
|
||||
- **Data Loss Prevention**: Consider DLP measures for sensitive data
|
||||
|
||||
## Auditing and Monitoring
|
||||
|
||||
### Comprehensive Logging
|
||||
|
||||
- **Detailed Logs**: Enable detailed logging for all operations
|
||||
- **Secure Log Storage**: Store logs securely with access controls
|
||||
- **Log Rotation**: Implement log rotation to manage disk space
|
||||
- **Tamper Protection**: Ensure logs cannot be modified or deleted
|
||||
|
||||
### Monitoring and Alerting
|
||||
|
||||
- **Real-time Monitoring**: Monitor for suspicious activities
|
||||
- **Security Alerts**: Configure alerts for security-related events
|
||||
- **Performance Monitoring**: Watch for performance issues that might indicate attacks
|
||||
- **Regular Review**: Establish a process for regular log review
|
||||
|
||||
## System Security
|
||||
|
||||
### Regular Updates
|
||||
|
||||
- **Update GoMFT**: Keep GoMFT updated to the latest version
|
||||
- **Patch Host System**: Keep the host operating system patched
|
||||
- **Update Dependencies**: Keep all dependencies (Docker, etc.) updated
|
||||
|
||||
### Backup and Recovery
|
||||
|
||||
- **Regular Backups**: Back up the GoMFT database and configurations regularly
|
||||
- **Secure Backups**: Encrypt backups and store them securely
|
||||
- **Test Restoration**: Regularly test backup restoration
|
||||
- **Disaster Recovery Plan**: Create and maintain a disaster recovery plan
|
||||
|
||||
## Periodic Security Review
|
||||
|
||||
### Security Assessments
|
||||
|
||||
- **Vulnerability Scanning**: Regularly scan for vulnerabilities
|
||||
- **Penetration Testing**: Conduct periodic penetration tests
|
||||
- **Configuration Review**: Review security configurations regularly
|
||||
- **Compliance Checks**: Ensure ongoing compliance with relevant standards
|
||||
|
||||
### Documentation
|
||||
|
||||
- **Security Policies**: Document security policies and procedures
|
||||
- **Configuration Documentation**: Maintain documentation of secure configurations
|
||||
- **Incident Response Plan**: Create and maintain an incident response plan
|
||||
|
||||
## Integrating with Security Tools
|
||||
|
||||
GoMFT can be integrated with external security tools:
|
||||
|
||||
- **SIEM Integration**: Forward logs to Security Information and Event Management tools
|
||||
- **Vulnerability Scanners**: Include GoMFT in vulnerability scanning
|
||||
- **Compliance Tools**: Integrate with compliance monitoring tools
|
||||
|
||||
## Best Practices for Specific Environments
|
||||
|
||||
### Cloud Deployment
|
||||
|
||||
- **Cloud Security Services**: Utilize cloud provider security services
|
||||
- **Network Security Groups**: Configure appropriate network security groups
|
||||
- **Private Endpoints**: Use private endpoints where possible
|
||||
- **Cloud IAM**: Leverage cloud Identity and Access Management
|
||||
|
||||
### On-Premises Deployment
|
||||
|
||||
- **Network Segmentation**: Place GoMFT in an appropriate network segment
|
||||
- **Physical Security**: Ensure physical security of the servers
|
||||
- **Environmental Controls**: Implement appropriate environmental controls
|
||||
- **Backup Power**: Ensure backup power for critical systems
|
||||
@@ -0,0 +1,235 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Running as Non-Root
|
||||
---
|
||||
|
||||
# Running GoMFT as a Non-Root User
|
||||
|
||||
By default, Docker containers run as the root user, which can pose security risks. GoMFT fully supports running as a non-root user, which is recommended for production environments.
|
||||
|
||||
## Benefits of Running as Non-Root
|
||||
|
||||
- **Improved Security**: Limits the potential damage if the container is compromised
|
||||
- **Better File Permissions**: Files created by the container will match your host user permissions
|
||||
- **Compliance**: Many security policies and best practices require containers to run as non-root
|
||||
|
||||
## Methods to Run GoMFT as Non-Root
|
||||
|
||||
GoMFT supports several methods for running as a non-root user, each with its own advantages.
|
||||
|
||||
### Method 1: Using PUID/PGID Environment Variables (Recommended)
|
||||
|
||||
This method allows changing the user at runtime without rebuilding the image:
|
||||
|
||||
```bash
|
||||
# Using current user's ID
|
||||
docker run -e PUID=$(id -u) -e PGID=$(id -g) starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
Or in docker-compose.yml:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
environment:
|
||||
- PUID=1000 # Your user ID
|
||||
- PGID=1000 # Your group ID
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
```
|
||||
|
||||
### Method 2: Using the `--user` Flag with Docker Run
|
||||
|
||||
This method is simple but doesn't support some advanced features like permission fixing:
|
||||
|
||||
```bash
|
||||
docker run --user $(id -u):$(id -g) starfleetcptn/gomft:latest
|
||||
```
|
||||
|
||||
### Method 3: Using Docker Compose with Environment Variables
|
||||
|
||||
This approach uses environment variables from the host for the user directive:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
user: "${UID:-1000}:${GID:-1000}"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
```
|
||||
|
||||
Run with:
|
||||
|
||||
```bash
|
||||
UID=$(id -u) GID=$(id -g) docker-compose up -d
|
||||
```
|
||||
|
||||
### Method 4: Building a Custom Image with Specified UID/GID
|
||||
|
||||
This method builds a custom image with your specified user ID:
|
||||
|
||||
```dockerfile
|
||||
FROM starfleetcptn/gomft:latest
|
||||
|
||||
ARG UID=1000
|
||||
ARG GID=1000
|
||||
|
||||
RUN usermod -u $UID gomft && groupmod -g $GID gomft
|
||||
```
|
||||
|
||||
In docker-compose.yml:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gomft:
|
||||
build:
|
||||
context: .
|
||||
args:
|
||||
UID: ${UID:-1000}
|
||||
GID: ${GID:-1000}
|
||||
```
|
||||
|
||||
## Environment Variables for User Management
|
||||
|
||||
| Variable | Description | Default |
|
||||
| -------- | ------------------ | ------------------------ |
|
||||
| PUID | User ID to run as | Built-in user ID (1000) |
|
||||
| PGID | Group ID to run as | Built-in group ID (1000) |
|
||||
| USERNAME | Username to use | gomft |
|
||||
|
||||
## Volume Permissions
|
||||
|
||||
When running as a non-root user, ensure that the directories on the host have appropriate permissions for the container user:
|
||||
|
||||
### Option 1: Create Directories with Correct Ownership (Recommended)
|
||||
|
||||
```bash
|
||||
# Create directories
|
||||
mkdir -p data backups
|
||||
|
||||
# Set ownership to match the PUID/PGID you'll use
|
||||
chown -R 1000:1000 data backups
|
||||
```
|
||||
|
||||
### Option 2: Adjust Permissions (Less Secure, but Easier for Testing)
|
||||
|
||||
```bash
|
||||
mkdir -p data backups
|
||||
chmod -R 777 data backups
|
||||
```
|
||||
|
||||
## Verifying Non-Root Operation
|
||||
|
||||
To verify that GoMFT is running as a non-root user:
|
||||
|
||||
```bash
|
||||
docker exec gomft id
|
||||
```
|
||||
|
||||
You should see output showing the UID and GID you specified.
|
||||
|
||||
## Troubleshooting Permission Issues
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Volume Mount Permission Denied**: The container user doesn't have permission to access mounted volumes
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
chown -R <PUID>:<PGID> ./data ./backups
|
||||
```
|
||||
|
||||
2. **Cannot Write to Log Files**: Permission issues with log files
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Ensure log directory exists and has correct permissions
|
||||
mkdir -p ./data/logs
|
||||
chown -R <PUID>:<PGID> ./data/logs
|
||||
```
|
||||
|
||||
3. **Database Permission Errors**: SQLite database permissions
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check and fix database file permissions
|
||||
chown <PUID>:<PGID> ./data/gomft.db
|
||||
chmod 644 ./data/gomft.db
|
||||
```
|
||||
|
||||
### Checking Container Logs for Permission Issues
|
||||
|
||||
```bash
|
||||
docker logs gomft | grep -i "permission denied"
|
||||
```
|
||||
|
||||
### Volume Permission Script
|
||||
|
||||
You can use this script to fix permissions on your data volumes:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Fix permissions for GoMFT volumes
|
||||
|
||||
# Set your PUID and PGID here
|
||||
PUID=1000
|
||||
PGID=1000
|
||||
|
||||
# Create directories if they don't exist
|
||||
mkdir -p ./data ./backups
|
||||
|
||||
# Fix ownership
|
||||
chown -R $PUID:$PGID ./data ./backups
|
||||
|
||||
echo "Permissions fixed for GoMFT volumes"
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
When running as non-root, there are still some security considerations:
|
||||
|
||||
- Avoid using `chmod 777` in production environments
|
||||
- Use volume binding with caution, especially for sensitive data
|
||||
- Consider using Docker secrets for sensitive credentials
|
||||
- Regularly update your GoMFT image to get the latest security fixes
|
||||
- Implement network segmentation to limit the container's access
|
||||
|
||||
## Example: Complete Docker Compose Setup with Non-Root User
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
gomft:
|
||||
image: starfleetcptn/gomft:latest
|
||||
container_name: gomft
|
||||
environment:
|
||||
- PUID=1000
|
||||
- PGID=1000
|
||||
- TZ=UTC
|
||||
- BASE_URL=http://localhost:8080
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
- ./backups:/app/backups
|
||||
ports:
|
||||
- "8080:8080"
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
||||
interval: 1m
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Always run GoMFT as a non-root user in production**
|
||||
2. **Use PUID/PGID environment variables for flexible user mapping**
|
||||
3. **Set appropriate permissions on volume mounts**
|
||||
4. **Verify the container is running as the expected user**
|
||||
5. **Follow least privilege principles for the container user**
|
||||
Reference in New Issue
Block a user