Deployment Guide

This comprehensive guide walks you through deploying applications on the Nimbuz platform. Learn about multiple deployment methods, configuration options, and deployment management.

Getting to Deployments

You can access the deployments section in two ways:

Option A: From Projects Page

1. Choose your project
2. Click the "Proceed" button at the bottom right of the Projects page

Option B: Direct Navigation

From the sidebar on the left, navigate to Deployments

Both options will take you to the same Deployments page where you can manage all your application deployments.

Deployments page overview with existing deployments and new deploy button

Creating a New Deployment

Step 1: Start New Deployment

Click "+ New Deploy" button on the right side of the Deployments screen.

Step 2: Choose Deployment Type

Click the dropdown labeled "Choose a type to continue."

You have three deployment options based on where your codebase is hosted:

1. Deploy from GitHub repo
2. Deploy from GitLab repo
3. Deploy zip

Choose your deployment method from the dropdown menu

Deployment Methods

Method 1: Deploy from GitHub Repository

Prerequisites

• Active GitHub account
• Repository with your application code
• Appropriate repository permissions

Steps

1. Select "Deploy from GitHub repo" from the dropdown
2. Enter your GitHub credentials to connect to your GitHub account
3. Authorize Nimbuz to access your repositories
4. Your branches and repositories will be loaded automatically
5. Select your target repository and branch

Benefits

• Automatic deployments on code push
• Version control integration
• Branch-based deployment strategies
• Easy rollback to previous versions

Method 2: Deploy from GitLab Repository

Prerequisites

• Active GitLab account
• Repository with your application code
• Appropriate repository permissions

Steps

1. Select "Deploy from GitLab repo" from the dropdown
2. Enter your GitLab credentials to connect to your GitLab account
3. Authorize Nimbuz to access your repositories
4. Your branches and repositories will be loaded automatically
5. Select your target repository and branch

Benefits

• GitLab CI/CD integration
• Merge request deployments
• Container registry support
• Advanced DevOps workflows

Method 3: Deploy from ZIP/TAR File

Prerequisites

• Application code packaged as ZIP or TAR file
• File size under 500 MB maximum

Steps

1. Select "Deploy zip" from the dropdown
2. Browse and select your ZIP or TAR file from local device
3. Click "Submit" to upload the file

Benefits

• Quick deployment for local development
• No external repository required
• Direct file upload capability
• Suitable for testing and prototyping

Deployment Configuration

After selecting your deployment method, configure your application with the following parameters:

General Configuration

Required Parameters

Name (required)

• Usually auto-populated from your repository name
• Must contain only lowercase letters, numbers, and separators (., -)
• Uppercase letters and consecutive separators are not allowed
• Must be unique within your project

Port

• The port your application listens on (e.g., 3000)
• Leave blank to use the default port
• Common ports: 3000 (Node.js), 8080 (Java), 5000 (Python)

Optional Parameters

Replicas

• Number of instances you want to run (default: 1)
• Higher replicas provide better availability and load distribution
• Consider your resource limits and traffic requirements

Build Command

• Command to build your project (e.g., npm run build)
• Executed during the build phase
• Common examples:
  • Node.js: npm run build
  • Python: pip install -r requirements.txt
  • Java: mvn clean package

Start Command

• Command to start your application (e.g., npm run start)
• Executed when your application starts
• Common examples:
  • Node.js: npm start or node server.js
  • Python: python app.py or gunicorn app:app
  • Java: java -jar app.jar

Install Command

• Command to install dependencies (e.g., npm install)
• Executed before the build command
• Framework detection often auto-populates this

Health Endpoint

• Path used for health checks (e.g., /health)
• Nimbuz uses this to monitor application health
• Should return HTTP 200 when application is healthy

Ephemeral Storage

• Temporary storage used during application runtime
• Cleared when application restarts
• Useful for temporary files and caching

Instance Type Selection

Choose the appropriate instance size based on your application requirements:

Instance Type	Description	Use Case
femto	Light weight reserved instance	Minimal applications, testing
pico	Very small instance for light usage	Small APIs, development
nano	Smallest instance for light usage	Microservices, simple apps
micro	Smaller instance for light usage	Small web apps, APIs
small	Small instance for light usage	Standard web applications
medium	Standard instance for general use	Production applications
large	High-capacity instance	High-traffic applications
extra large	Max-performance instance	Resource-intensive apps
2x large	Ultra-Max performance instance	Enterprise applications

Considerations for Instance Selection

• CPU Requirements: Computational intensity of your application
• Memory Usage: RAM requirements for your application
• Traffic Volume: Expected concurrent users and requests
• Cost Optimization: Balance performance needs with budget

Environment Variables

Configure your application's runtime behavior with environment variables.

What are Environment Variables?

Key-value pairs used to configure application behavior at runtime. Commonly used for:

• Environment types (e.g., Dev, Prod)
• API endpoints and URLs
• Feature flags and toggles
• Configuration parameters

Adding Environment Variables

1. Navigate to the Environment Variables section

2. Add key-value pairs for your application

3. Examples:

   NODE_ENV=production
   API_URL=https://api.example.com
   DEBUG=false
   PORT=3000

Best Practices

• Use descriptive names for your variables
• Avoid storing sensitive data as environment variables
• Use consistent naming conventions
• Document important environment variables

Secrets Management

Securely store sensitive information like passwords, API keys, and tokens.

What are Secrets?

Sensitive key-value pairs that are:

• Stored securely and encrypted
• Injected into applications at runtime
• Never exposed in codebase or logs
• Managed separately from regular environment variables

Adding Secrets

1. Navigate to the Secrets section

2. Add sensitive key-value pairs

3. Examples:

   DATABASE_PASSWORD=your-secure-password
   API_KEY=your-api-key
   JWT_SECRET=your-jwt-secret

Security Best Practices

• Never commit secrets to version control
• Rotate secrets regularly
• Use different secrets for different environments
• Limit access to secrets based on roles

Code as Config

Upload configuration files for advanced application setup.

What is Code as Config?

• Upload a config.yml file from your application
• Specify the file path from the root of your application
• Provides advanced configuration options
• Enables infrastructure as code practices

Using Code as Config

1. Navigate to the Code as Config section
2. Upload your configuration file
3. Specify the file path from your application root
4. Common file formats: YAML, JSON, TOML

Deployment Review and Submission

Final Review

Before deploying, review all your configuration:

• Application Details: Name, instance type, replicas
• Build Configuration: Commands and settings
• Environment Setup: Variables and secrets
• Network Configuration: Ports and health endpoints
• Resource Allocation: Storage and compute resources

Submit Deployment

1. Review all configuration details
2. Make any necessary changes
3. Click "Submit" to start the deployment process
4. You'll be redirected to the Deployments screen
5. Click the project name to view deployment progress

Deployment States

Understanding your deployment's lifecycle:

1. Initiated

• Deployment created successfully
• Status marked as "Initiated"
• Transitions to "Building" when system is ready

2. Building

• Nimbuz uses Nixpacks to build the application
• Docker image is created and pushed to ECR repository
• Further actions like redeploy are restricted during this phase
• Build logs are available for monitoring

3. Deploying

• Build completed successfully
• System pulls image from ECR
• Application is being deployed to infrastructure
• Infrastructure resources are being provisioned

4. Active

• Deployment completed successfully
• Application is up and ready for use
• Health checks are passing
• Application is serving traffic

5. Pending

• Application cannot be accessed or initialized
• Resources may not be fully provisioned
• Temporary state during scaling or updates
• Usually resolves automatically

6. Stopped

• Application manually paused or stopped
• Resources are preserved but not running
• Can be resumed when needed
• No traffic is being served

7. Failed

• Build or deploy process failed
• Logs available to help troubleshoot
• Application is not accessible
• Requires investigation and redeployment

Managing Deployments

Viewing Deployment Details

Click on any deployment name to access detailed information including:

• Active Release: Current deployment status and timeline
• History: Previous deployment attempts and releases
• Environment Variables: Runtime configuration
• Secrets: Secure configuration management
• Code as Config: Configuration file management
• Settings: General deployment settings
• Application Logs: Real-time and historical logs
• Metrics: Performance and resource usage

Deployment Actions

View Logs

• Access detailed build and deploy logs
• Search functionality for finding specific entries
• Real-time log streaming
• Error identification and debugging

Redeploy

• Re-initiate build and deploy stages
• Current active release marked as "Superseded"
• Moved to History tab
• Uses current configuration settings

Pause/Resume

• Pause: Stops application, status becomes "Stopped"
• Resume: Restarts paused application
• Resources are preserved during pause
• Quick way to temporarily stop traffic

Release Management

Active Release Information

• Deployment trigger timestamp
• Timeline of all deployment stages
• Status of each stage (Building, Deploying, Active)
• Duration taken by each stage
• Success/failure indicators

Release History

• Previous deployment attempts
• Superseded releases
• Rollback capabilities
• Performance comparisons

Advanced Configuration

Networking Configuration

Domain Generation

• Click "Generate Domain" for public HTTP access
• Creates a public URL for your application
• Displays domain availability status immediately
• SSL certificates automatically provisioned

Custom Domain

Custom DNS allows you to use your own "domain" or "subdomain" (for example, yourdomain.com or app.yourdomain.com) instead of a default service URL.

It maps your domain to a specific server or application using DNS records such as CNAME or A records.

• Enable "Custom DNS" to add your DNS

Setup Custom DNS

Follow these steps for Setup your Domain

1. Fill in the fields below to add a CNAME record.
2. The DNS Name field is read-only and is auto-generated.
3. Use the Host field to enter your subdomain (e.g. app).
4. Click Generate to complete the setup. It may take a few minutes for the changes to take effect.

Authentication

• Enable Basic Authentication for additional security
• Provide username and password credentials
• Click "Generate" to secure access
• Protects applications with simple authentication

Application Updates

Source Updates

• Update deployment type (ZIP/VCS)
• Upload new ZIP/TAR files for ZIP deployments
• Triggers build stage when changes are saved
• Version control for deployment sources

Settings Updates

• Modify replicas, ports, storage allocation
• Update build and start commands
• Change health check endpoints
• Triggers deploy stage when saved

Monitoring and Observability

Application Logs

• Real-time log streaming
• Historical log access
• Time interval filters
• Custom date range selection
• Search and filtering capabilities
• Default: Last 15 minutes of logs

Application Metrics

• CPU usage graphs and trends
• RAM utilization monitoring
• Pod-level metrics collection
• Time duration filters
• Interval selection options
• Visual performance insights

Troubleshooting

Common Deployment Issues

Build Failures

• Check build command syntax
• Verify dependencies are properly specified
• Review build logs for specific errors
• Ensure proper file structure

Runtime Errors

• Check start command configuration
• Verify port configuration
• Review application logs
• Check environment variables and secrets

Health Check Failures

• Verify health endpoint returns HTTP 200
• Check if endpoint exists and is accessible
• Review application startup time
• Ensure health check path is correct

Getting Help

• Review deployment logs for error messages
• Check application metrics for resource issues
• Consult troubleshooting documentation
• Contact support for persistent issues

Best Practices

Deployment Strategy

• Use staging environments for testing
• Implement proper CI/CD workflows
• Test deployments thoroughly before production
• Monitor applications after deployment

Configuration Management

• Keep environment-specific configurations separate
• Use secrets for sensitive information
• Document configuration requirements
• Version control configuration files

Resource Management

• Right-size instances based on actual usage
• Monitor resource utilization regularly
• Scale replicas based on traffic patterns
• Optimize build and runtime performance

Next Steps

With your application deployed, explore:

1. Tools and Services - Add databases and services
2. Dashboard Monitoring - Monitor performance
3. Resource Management - Optimize resources
4. User Management - Manage team access

Support

Need help with deployments?

• Email: deployments@nimbuz.cloud
• Live Chat: Available 24/7 in your dashboard
• Documentation: Comprehensive deployment guides
• Video Tutorials: Step-by-step deployment walkthroughs