Documentation

Everything you need to know about deploying and managing your projects on Shipoff

Getting Started

1. Create an Account

Visit console.shipoff.in/signin and create your account. You can sign up with your email or use GitHub OAuth for a faster setup.

✓ Email/Password signup

✓ GitHub OAuth integration

2. Connect GitHub

Link your GitHub account to enable deployments

During project creation, you'll be prompted to install the Shipoff GitHub App. This allows us to:

Access your repositories for deployment
Set up webhooks for automatic deployments
Create preview deployments for pull requests
Access repository metadata (commits, branches, etc.)

3. Create Your First Project

Follow the project creation wizard

Navigate to Dashboard → Projects → Create Project to start the wizard:

Project Info: Name and description
Framework: Select your framework (auto-detected if possible)
Repository: Connect your GitHub repository
Domain: Choose your project domain
Environment Variables: Add secrets and config (optional)

4. Deploy

Your first deployment happens automatically

Once your project is created, Shipoff automatically triggers your first deployment. You can:

Watch the build progress in real-time
View deployment logs
Access your live site once deployment completes

Managing Projects

Project Types

Understanding static vs dynamic projects

Static Projects

• React, Vue, Angular apps
• Static site generators
• Always available (no sleep)
• Served via CDN
• Free tier: 4 projects

Dynamic Projects

• Node.js, Python, PHP apps
• Full-stack applications
• Auto-scaling
• Server-side rendering
• Free tier: 1 project

⚠️ Free Tier Autoscaling:

Dynamic projects on the free tier automatically scale down to 0 instances after 15 minutes of inactivity. The first request after scaling down will experience a cold start delay.

Project Configuration

Setting up build and runtime commands

Build Command

The command that builds your application. For static sites, this creates the production bundle. For dynamic apps, this installs dependencies.

# Static (React/Vue/etc)

npm run build

# Dynamic (Node.js)

npm install && npm run build

# Python

pip install -r requirements.txt

Production Command

For dynamic projects, this is the command that starts your server. Static projects use "N/A".

# Node.js (Express)

node server.js

# Python (Flask)

gunicorn app:app

Free Tier Limits

Resource and time constraints for free tier projects

Time Limits

Build Timeout: All free tier projects have a 5-minute (300 seconds) limit to complete the build process. If your build takes longer, the deployment will fail with aBUILD_TIMEOUT error.
Server Startup Timeout: Dynamic projects must start their server and respond to health checks within 5 minutes (300 seconds). If your server doesn't start in time, the deployment will fail with a SERVER_STARTUP_TIMEOUT error.

Tip: Optimize your build times by using build caches, minimizing dependencies, and ensuring your production command starts quickly. Consider upgrading for longer time limits.

Resource Limits

Memory Limit: Free tier projects are limited to 512MB of RAM. If your application exceeds this limit during build or runtime, it will be terminated with aMEMORY_LIMIT_EXCEEDED error.

Tip: Monitor your memory usage and optimize your application. Consider reducing dependency sizes or upgrading for more resources.

Autoscaling Behavior

Scale-to-Zero: Free tier dynamic projects automatically scale down to 0 instances after15 minutes of inactivity. When there are no incoming requests for 15 minutes, your application will be scaled to zero.
Cold Start: The first request after scaling to zero will experience a cold start delayas the application instance needs to be provisioned and started. This typically takes a few seconds.
Active Scaling: Once a request arrives, the instance scales up automatically and serves subsequent requests without delay until the 15-minute inactivity period begins again.

Note: This behavior only applies to free tier dynamic projects. Static projects are always available and do not scale to zero. Consider upgrading if you need always-on availability for your dynamic applications.

Summary:

• Build must complete: ≤ 5 minutes

• Server startup (dynamic): ≤ 5 minutes

• Memory limit: 512MB

• Auto-scale to zero: 15 min inactivity (dynamic only)

Deployments

Automatic Deployments

How auto-deploy works

Shipoff automatically deploys your application whenever you push to your connected branch (usually main or master).

Deployment Flow:

Push code to your repository
GitHub webhook notifies Shipoff
Build process starts
Application is deployed to edge network
Your site is live!

Viewing Logs

Monitoring your deployments

Access real-time logs from the Deployments page:

Build Logs: Output from your build command
Runtime Logs: Application output and errors
Deployment Logs: Infrastructure provisioning messages

Deployment State Machine

Understanding the Deployment Lifecycle

How deployments progress through states in sequence

Every deployment in Shipoff follows a strict state machine. Understanding this lifecycle and the sequence of states is essential for managing your deployments effectively. Deployments progress through states in a specific order, and each state has specific rules about what operations are allowed.

Critical Rules

• Only INACTIVE and FAILED deployments can be deleted or redeployed
• PRODUCTION deployments cannot be deleted (they protect your live site)
• Deployments in QUEUED, BUILDING, or PROVISIONING must complete before actions can be taken
• Only one PRODUCTION deployment exists per project at a time
• When a new deployment reaches PRODUCTION, the previous PRODUCTION automatically becomes INACTIVE

1QUEUED - The Starting Point

When you push code or create a new deployment, it starts in the QUEUED state. The deployment is waiting in line to be processed by the build system.

Next state:BUILDING

Cannot be deleted or redeployed while in this state. Must wait for state transition.

2BUILDING - Compiling Your Code

The build system is now executing your build command. This includes installing dependencies, compiling code, and creating the production bundle. This is where most build errors occur.

Can transition to:PROVISIONINGorFAILED

Cannot be deleted or redeployed while building. If build fails, transitions to FAILED state.

Free Tier: Build must complete within 5 minutes. Long builds will timeout and fail.

3PROVISIONING - Setting Up Runtime

Once the build succeeds, the runtime environment is being provisioned. This includes setting up containers, configuring networking, and preparing the deployment to serve traffic.

Can transition to:PRODUCTIONorFAILED

Cannot be deleted or redeployed while provisioning. If provisioning fails, transitions to FAILED state.

Dynamic Projects: Server must start and respond to health checks within 5 minutes. Ensure your server starts quickly and the PORT environment variable is correctly configured.

4PRODUCTION - Live and Serving Traffic

Protected - Cannot be deleted

The deployment is now live and serving production traffic. This is your active deployment. Only one deployment can be in PRODUCTION state per project at any given time.

Important: When a new deployment reaches PRODUCTION, the previous PRODUCTION deployment automatically transitions to INACTIVE. This ensures only one active deployment at a time.

Protected state - cannot be deleted to prevent accidental downtime. Automatically becomes INACTIVE when replaced by a new PRODUCTION deployment.

Terminal States - Operations Allowed

These states are "stable" terminal states where deployments can remain indefinitely. Operations like delete and redeploy are only available in these states.

5INACTIVE - Previous Production Deployment

✓ Deletable✓ Redeployable

This deployment was previously in PRODUCTION but has been replaced by a newer deployment. It's no longer serving traffic but retains all its data and can be reactivated or deleted.

Operations available: You can delete this deployment to free up resources, or redeploy it to make it active again (transitions back to QUEUED).

Stable terminal state - safe to delete or redeploy at any time.

6FAILED - Error State

✓ Deletable✓ Redeployable

The deployment encountered an error during BUILDING or PROVISIONING. The deployment process has stopped and is not serving traffic.

Common causes: Build command failure, dependency errors, runtime provisioning issues, or configuration problems.

Operations available: You can delete this deployment to remove it, or redeploy it (after fixing issues) which transitions it back to QUEUED.

Stable terminal state - safe to delete or redeploy. Check logs to identify and fix the error before redeploying.

Complete State Machine Flow Diagram

Sequential flow of deployment states

Primary Success Path:

QUEUED

BUILDING

PROVISIONING

PRODUCTION

(Live)

Error Paths:

BUILDINGFAILED(on build error)

PROVISIONINGFAILED(on provisioning error)

Production Replacement:

New deployment reaches PRODUCTION

Previous PRODUCTIONINACTIVE(automatic transition)

Redeployment Path:

INACTIVEorFAILED→ User clicks Redeploy →QUEUED(restarts lifecycle)

Operations Available by State

What you can do with deployments in each state

State	View Logs	Redeploy	Delete	Notes
QUEUED	✓	✗	✗	Waiting to start
BUILDING	✓	✗	✗	Build in progress
PROVISIONING	✓	✗	✗	Setting up runtime
PRODUCTION	✓	✗	✗ Protected	Live deployment
INACTIVE	✓	✓	✓	Replaced by newer deployment
FAILED	✓	✓	✓	Error occurred

Supported Frameworks

Framework Reference

Default configurations for supported frameworks

Framework	Type	Runtime	Build Command	Output Dir
Next.js	Static/Dynamic	Node.js	npm run build	.next
React	Static	Node.js	npm run build	build
Vue	Static	Node.js	npm run build	dist
Vite	Static	Node.js	npm run build	dist
Express	Dynamic	Node.js	npm install	N/A
Nest.js	Dynamic	Node.js	npm run build	dist
Fastify	Dynamic	Node.js	npm install	N/A
Django	Dynamic	Python	pip install -r requirements.txt	staticfiles
Flask	Dynamic	Python	pip install -r requirements.txt	N/A
FastAPI	Dynamic	Python	pip install -r requirements.txt	N/A
Laravel	Dynamic	PHP	composer install	public
Symfony	Dynamic	PHP	composer install	public

Environment Variables

Managing Secrets

Securely managing secrets and configuration

Environment variables are encrypted at rest and injected into your build and runtime environments. They're never exposed in logs or the UI.

Required for Dynamic Projects

Dynamic projects must set the PORT environment variable. This is the port number your application listens on (e.g., 3000,8000). Without this variable, your deployment will fail during health checks.

Example:

PORT=3000

Best Practices:

Use descriptive names (e.g., DATABASE_URL not DB)
Never commit secrets to your repository
Use different values for different environments if needed
Rotate secrets regularly
Dynamic projects: Always set PORT to match your application's listening port

Teams & Collaboration

Working with Teams

Collaborate on projects with your team

Invite team members, manage permissions, and collaborate on projects. Team features include:

Role-based access control
Project sharing
Team analytics
Audit logs

Troubleshooting

Build Failures

Common causes:

Missing dependencies in package.json/requirements.txt
Incorrect build command
Missing environment variables (especially PORT for dynamic projects)
Build timeout: Free tier projects have a 5-minute build limit. Optimize your build process if it's taking too long
Memory limit exceeded: Projects are limited to 512MB RAM. Reduce dependencies or optimize memory usage
Server startup timeout: Dynamic projects must start within 5 minutes. Ensure your server starts quickly and responds on the configured PORT

Deployment Not Triggering

If deployments aren't triggering automatically:

Verify GitHub App is installed on your repository
Check that you're pushing to the correct branch
Ensure webhook is configured in GitHub
Check project repository settings

Cannot Delete/Redeploy Deployment

If you're unable to delete or redeploy a deployment:

PRODUCTION deployments cannot be deleted (this protects your live site)
Deployments in QUEUED, BUILDING, or PROVISIONING must complete first
Wait for the deployment to reach INACTIVE or FAILED state
Only stable states allow deletion and redeployment

Need More Help?

If you're still experiencing issues, reach out to our support team at teamshipoff@gmail.com or use the "Report Bug" feature in your dashboard.