Platform Setup
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.
Accessing Platform Settings
Log in as Administrator
Access your DeployStack instance and log in with an administrator account.
Navigate to Settings
Go to Settings → Global Settings to access all configuration options.
Configure Settings
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 | [email protected] |
| 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) | [email protected] |
Email Provider Setup
Gmail Configuration:
- Enable 2-Factor Authentication at Google Account Security
- Generate App Password at App Passwords
- Configure in DeployStack:
SMTP Host: smtp.gmail.com
SMTP Port: 587
Username: [email protected]
Password: [16-character app password]
Use SSL/TLS: YesUse the app password, not your regular Gmail password.
Outlook/Office 365 Configuration:
SMTP Host: smtp-mail.outlook.com (or smtp.office365.com)
SMTP Port: 587
Username: [email protected]
Password: [your password or app password]
Use SSL/TLS: YesSendGrid Configuration:
- Create API Key in SendGrid dashboard
- Configure in DeployStack:
SMTP Host: smtp.sendgrid.net
SMTP Port: 587
Username: apikey
Password: [your SendGrid API key]
Use SSL/TLS: YesThe 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: YesAmazon SES:
SMTP Host: email-smtp.[region].amazonaws.com
SMTP Port: 587
Username: [SES SMTP username]
Password: [SES SMTP password]
Use SSL/TLS: YesTesting Email Configuration
After configuring SMTP settings:
- Save Configuration - Click "Save" to store your SMTP settings
- Test Email Sending - Use the "Send Test Email" button if available
- Check Email Delivery - Verify the test email arrives (check spam folder)
- Enable Email Sending - Set "Send Mail" to
Yesin Global Settings
Setup Workflow
Follow this recommended setup workflow for new DeployStack instances:
Initial Access
- Complete the initial setup wizard
- Create your admin account
- Log in to the platform
Configure Global Settings
- Set the correct Frontend URL for your domain
- Configure login and registration preferences
- Disable API documentation for production
Set Up Email (Recommended)
- Configure SMTP settings for your email provider
- Test email delivery
- Enable email sending in Global Settings
Verify Configuration
- Test user registration (if enabled)
- Test password reset functionality
- Verify email notifications work
Create Users and Teams
- Invite team members
- Set up user roles and permissions
- Configure team workspaces
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
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 you're logged in as an administrator
- Check that your user has the
global_adminrole - Verify the backend service is running properly
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
- Documentation: Consult our troubleshooting guide
- 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
Your platform settings are stored in the database. Ensure you:
- Backup the database regularly (included in persistent volume)
- Document custom settings for disaster recovery
- Test restore procedures in non-production environments
Next Steps: After completing platform setup, configure user roles and permissions and set up your first team workspaces.