Skip to content

setup.mdx

Latest commit

 

History

History
409 lines (302 loc) · 13.6 KB

setup.mdx

File metadata and controls

409 lines (302 loc) · 13.6 KB
Raw
title Platform Setup
description Configure your self-hosted DeployStack instance with global settings, email functionality, and platform features.

Configure your self-hosted DeployStack instance with essential settings to customize functionality, enable features, and optimize the platform for your organization.

Platform setup is performed through the web interface after your DeployStack instance is running. All settings are optional but recommended for production deployments.

Initial Setup Process

**For Developers**: The initial setup consists of two parts: 1. **Database Setup**: Completed via the frontend wizard at `/setup` which calls `POST /api/db/setup` 2. **Platform Configuration**: Done through the Settings interface after database initialization

Accessing Platform Settings

If this is a fresh installation, first visit `https:///setup` to complete the database initialization wizard. This creates: 
**For Docker deployments:**
- PostgreSQL database configuration stored in the Docker volume `deploystack_backend_persistent`
- PostgreSQL data stored in `deploystack_postgres_data` volume
- Access the setup wizard at `http://localhost:8080/setup` (or your configured frontend URL)

**For local development:**
- PostgreSQL connection configured via environment variables in `services/backend/.env`
- `services/backend/persistent_data/db.selection.json` (database initialization status)
After database setup, access your DeployStack instance and log in with an administrator account. Go to **Settings** → **Global Settings** to access all configuration options. Use the tabs to configure different aspects of your DeployStack instance.

Global Platform Settings

Configure core platform functionality and features.

Application Configuration

Setting Description Default Recommended
Frontend URL Base URL where your DeployStack frontend is accessible http://localhost:5173 Your actual domain (e.g., https://deploystack.company.com)
Enable Login Allow users to log in to the platform Yes Yes (disable only for maintenance)
Enable Email Registration Allow new users to register with email Yes Yes (or No for invite-only)
Enable API Documentation Show Swagger API docs at /documentation Yes No for production (security)

Feature Toggles

Setting Description Default Use Case
Send Mail Enable email sending functionality No Yes after SMTP configuration

Email Configuration (SMTP)

Configure email functionality to enable notifications, password resets, and user communications.

Email configuration is **optional** but highly recommended for production deployments. Without email, users cannot reset passwords or receive notifications.

Why Configure Email?

With email configured, DeployStack can:

  • Send password reset emails when users forget their passwords
  • Send user invitations to join teams and workspaces
  • Notify users about deployment status and important events
  • Send welcome emails to new users
  • Provide account verification for enhanced security

SMTP Configuration

Navigate to Settings → Global Settings → SMTP Mail Settings tab.

Required Settings

Setting Description Example
SMTP Host Your email provider's SMTP server smtp.gmail.com
SMTP Port Port number for SMTP connection 587 (TLS) or 465 (SSL)
Username Your email account username your-email@gmail.com
Password Your email account password or app password your-app-password

Optional Settings

Setting Description Default Example
Use SSL/TLS Enable secure connection Yes Recommended: Yes
From Name Display name for sent emails DeployStack Your Company Name
From Email Email address for sent emails (uses username) noreply@yourcompany.com

Email Provider Setup

```text Gmail Gmail Configuration:
  1. Enable 2-Factor Authentication at https://myaccount.google.com/security
  2. Generate App Password at https://myaccount.google.com/apppasswords
  3. Configure in DeployStack:

SMTP Host: smtp.gmail.com SMTP Port: 587 Username: your-email@gmail.com Password: [16-character app password] Use SSL/TLS: Yes


```text Outlook
Outlook/Office 365 Configuration:

SMTP Host: smtp-mail.outlook.com (or smtp.office365.com)
SMTP Port: 587
Username: your-email@outlook.com
Password: [your password or app password]
Use SSL/TLS: Yes

SendGrid Configuration:

1. Create API Key in SendGrid dashboard
2. Configure in DeployStack:

SMTP Host: smtp.sendgrid.net
SMTP Port: 587
Username: apikey
Password: [your SendGrid API key]
Use SSL/TLS: Yes

Note: The username is literally "apikey" for SendGrid.

Other Providers:

Mailgun:
SMTP Host: smtp.mailgun.org
SMTP Port: 587
Username: [Mailgun SMTP username]
Password: [Mailgun SMTP password]
Use SSL/TLS: Yes

Amazon SES:
SMTP Host: email-smtp.[region].amazonaws.com
SMTP Port: 587
Username: [SES SMTP username]
Password: [SES SMTP password]
Use SSL/TLS: Yes
**Gmail Users**: Use the app password, not your regular Gmail password.

Testing Email Configuration

After configuring SMTP settings:

  1. Save Configuration - Click "Save" to store your SMTP settings
  2. Test Email Sending - Use the "Send Test Email" button if available
  3. Check Email Delivery - Verify the test email arrives (check spam folder)
  4. Enable Email Sending - Set "Send Mail" to Yes in Global Settings

Setup Workflow

Follow this recommended setup workflow for new DeployStack instances:

- Navigate to `https:///setup` (Docker: `http://localhost:8080/setup` by default) - Complete the database setup wizard (PostgreSQL) - This initializes the PostgreSQL database and applies migrations - Create your admin account - Log in to the platform - Set the correct Frontend URL for your domain - Configure login and registration preferences - Disable API documentation for production - Configure SMTP settings for your email provider - Test email delivery - Enable email sending in Global Settings - Test user registration (if enabled) - Test password reset functionality - Verify email notifications work - Invite team members - Set up user roles and permissions - Configure team workspaces - Navigate to Admin → Satellites → Pairing - Generate registration tokens for new satellites - Deploy satellite services with registration tokens - Verify satellite registration and health 
For satellite deployment instructions, see [Quick Start - Satellite Service](/self-hosted/quick-start#satellite-service).

Satellite Administration

Satellites are **required** for DeployStack to function. Without satellites, you cannot manage MCP servers. Deploy at least one satellite after completing the platform setup.

Generating Registration Tokens

Administrators can generate registration tokens for new satellites:

  1. Navigate to Satellite Management:

    • Log in as global_admin
    • Go to Admin → Satellites → Pairing

  2. Generate Token:

    • Click "Generate Token"
    • Copy the full token (starts with deploystack_satellite_global_)
    • Token expires in 1 hour for security

  3. Deploy Satellite:

Token Security

  • Single-Use: Registration tokens are consumed after successful pairing
  • Expiration: Global tokens expire after 1 hour
  • Scope: All self-hosted satellites are global satellites by default
  • Admin Only: Only global_admin users can generate registration tokens

Satellite Status Management

After registration, satellites appear in the admin panel with inactive status:

  1. Activate Satellite:

    • Navigate to Admin → Satellites
    • Find your registered satellite
    • Click "Activate" to enable it

  2. Monitor Health:

    • View heartbeat status and system metrics
    • Check last communication timestamp
    • Review process status and resource usage

Security Considerations

Production Security

  • Disable API Documentation (Enable API Documentation: No) in production
  • Use HTTPS for Frontend URL in production environments
  • Restrict Registration (Enable Email Registration: No) for private deployments
  • Use Strong SMTP Passwords and enable 2FA on email accounts
  • Secure Satellite Tokens: Store registration tokens securely and don't commit to version control

Email Security

  • Use App Passwords for Gmail and Outlook when 2FA is enabled
  • Enable TLS/SSL for SMTP connections
  • Monitor Email Activity through your email provider's dashboard
  • Set Up Domain Authentication (SPF, DKIM, DMARC) for better delivery

Troubleshooting

Common Setup Issues

Cannot Access Settings

Problem: Settings page not accessible or returns errors

Solutions:

  • Ensure the initial database setup at /setup has been completed
  • For Docker: Check that the deploystack_backend_persistent volume exists and contains data
  • For local development: Check for services/backend/persistent_data/db.selection.json file existence
  • Ensure you're logged in as an administrator
  • Check that your user has the global_admin role
  • Verify the backend service is running properly
  • Check that database migrations have been applied (happens automatically after setup)

Email Not Working

Problem: SMTP configuration fails or emails not delivered

Solutions:

  • Check credentials: Verify username and password are correct
  • Test connectivity: Ensure your server can reach SMTP ports (587, 465)
  • Check spam folders: Emails might be marked as spam
  • Verify provider settings: Confirm SMTP host and port are correct

Frontend URL Issues

Problem: Redirects or links point to wrong URLs

Solutions:

  • Update Frontend URL: Set the correct domain in Global Settings
  • Check environment variables: Ensure Docker containers have correct URLs
  • Restart services: Restart after changing URL settings

Getting Help

If you encounter issues during setup:

  • Check logs: Review Docker container logs for error messages
  • Community: Join our Discord for support
  • GitHub: Report issues on our GitHub repository

Advanced Configuration

Environment-Specific Settings

Configure different settings for different environments:

Development:

  • Enable API documentation for testing
  • Use localhost URLs
  • Optional email configuration

Staging:

  • Mirror production settings
  • Use staging domain URLs
  • Enable email for testing

Production:

  • Disable API documentation
  • Use production domain URLs
  • Enable all email functionality
  • Restrict registration if needed

Backup Configuration

```bash Docker Deployment # Docker Volume Backup: # Your data is stored in the Docker volume deploystack_backend_persistent. To backup:

Create a backup of the Docker volume

docker run --rm -v deploystack_backend_persistent:/data
-v $(pwd):/backup alpine
tar czf /backup/deploystack-backup-$(date +%Y%m%d).tar.gz /data

Restore from backup:

Restore the Docker volume from backup

docker run --rm -v deploystack_backend_persistent:/data
-v $(pwd):/backup alpine
tar xzf /backup/deploystack-backup-20250108.tar.gz -C /

The volume contains:

- db.selection.json - Database initialization status

- Any other persistent application data

Note: PostgreSQL data is stored separately in deploystack_postgres_data volume


```bash Local Development
# File System Backup:
# Your data is stored in services/backend/persistent_data/. To backup:

# Create a backup archive
tar czf deploystack-backup-$(date +%Y%m%d).tar.gz \
  services/backend/persistent_data/

# Restore from backup:
# Restore from backup archive
tar xzf deploystack-backup-20250108.tar.gz

# The directory contains:
# - db.selection.json - Database initialization status
# - Any other persistent application data
# Note: PostgreSQL runs separately via Docker (npm run postgres:local)
**Important**: Always backup the complete data directory/volume, not just the database file, as it contains critical configuration like database type selection.
  • Document custom settings for disaster recovery
  • Test restore procedures in non-production environments
  • Schedule regular backups using cron or your preferred scheduling tool

Next Steps: After completing platform setup, configure user roles and permissions and set up your first team workspaces.