Environments & Domains

🌐 Map branches from your GitHub repository to domains and servers, and manage domain settings.

This guide explains how WEMAZU handles branches and domains: we read branches from GitHub (we do not create them), and you map any branch to a domain, server, and deploy path. You can add as many such mappings as you want.

Table of Contents

  1. How Branches and Domains Work
  2. Branch-to-Domain Mapping
  3. Domain Configuration
  4. Default WEMAZU Domains
  5. Custom Domains
  6. DNS Configuration
  7. Domain Switching

How Branches and Domains Work

WEMAZU Does Not Create Branches

Your Git branches live in your GitHub repository. WEMAZU reads the list of branches from GitHub; we do not create or modify branches. When you add a domain, you select which branch to deploy and map it to a server and deploy path. You can add as many branch→domain/server mappings as you want (e.g. one domain with one branch, or one domain with several branches each with their own server/path).

What You Configure

  • Domain: The URL where the app is accessible (e.g. example.com, staging.example.com).
  • Branch: Chosen from the branches we read from your repo (e.g. main, develop, feature/x).
  • Server: The server that hosts the files (FTP, SFTP, or SSH/VPS).
  • Deploy path: The directory on that server where files are deployed.

You might use one domain for a “staging” setup (e.g. branch develop → staging.example.com) and another for “production” (e.g. branch main → example.com). Those are naming conventions you choose; WEMAZU does not auto-create any fixed staging or production branches or environments.

Branch-to-Domain Mapping

How Mapping Works

For each domain you add, you configure one or more branch rows. Each row is: branch (from GitHub) + server + deploy path + optional auto-deploy. There is no fixed “staging” or “production” environment—you decide which branch goes to which domain and server.

Domain Branches

Each domain can have multiple branch configurations:

Example:

Domain: example.com
├── Branch: main → Server A → /var/www/production (auto-deploy: ON)
├── Branch: develop → Server A → /var/www/staging (auto-deploy: ON)
└── Branch: feature/test → Server A → /var/www/test (auto-deploy: OFF)

Key Points:

  • ✅ Branches are read from GitHub; you select which to use.
  • ✅ Multiple branches can deploy to the same domain (with different paths).
  • ✅ Each branch row has its own server and deploy path.
  • ✅ Auto-deploy can be enabled or disabled per branch.
  • ✅ Branch names are case-insensitive (normalized).

Path Resolution

When deploying, WEMAZU uses the deploy path for the branch configuration you chose (domain branch row). If that row has a deploy path set, that is used; otherwise the domain’s default deploy path is used. If no path is configured for that branch, deployment fails with a clear error.

Domain Configuration

What is a Domain?

A domain in WEMAZU represents:

  • A URL where your application is accessible
  • A connection to a server
  • A deployment path on that server
  • Branch configurations for auto-deploy

Domain Structure

Each domain has:

  • Domain Name: The URL (e.g., example.com, staging.example.com)
  • Project: Linked to a specific project
  • Server: The server where files are deployed
  • Deploy Path: Absolute path on server (e.g., /var/www/html)
  • Status: pending, active, deploying, error, failed
  • Is Primary: Boolean flag for primary domain

Creating a Domain

Step 1: Navigate to Project

Go to your Project → Domains tab.

Step 2: Click "Add Domain"

Click the "Add Domain" button.

Step 3: Fill in Domain Details

Required Fields:

  • Domain Name: Your domain (e.g., example.com or staging.example.com)
    • ✅ Can include paths: example.com/path
    • ✅ Automatically removes http://, https://, www. prefixes
  • Server: Select a server from your servers list
  • Deploy Path: Absolute path on server (e.g., /var/www/html)

Optional Fields:

  • Is Primary: Mark as primary domain (affects display order)
  • Branches: Configure branch-specific settings:
    • Branch name
    • Custom deploy path (overrides domain default)
    • Auto-deploy (enable/disable)

Step 4: Save Domain

Click "Save Domain". The domain is created with status pending.

Domain Status

Status Values:

  • pending: Domain created but not yet deployed
  • active: Domain has successful deployment
  • deploying: Deployment in progress
  • error: Last deployment failed
  • failed: Domain configuration error

Status Transitions:

pending → deploying → active
                  ↓
                error

Default WEMAZU Domains

What are Default Domains?

WEMAZU does not automatically create default domains. You must manually configure domains for each project.

However, WEMAZU can work with subdomains if you configure them:

Example Configuration:

Project: My Web App
├── Domain 1: staging.myapp.wemazu.com → branch develop → your server
└── Domain 2: myapp.wemazu.com → branch main → your server

Using WEMAZU Subdomains

If WEMAZU provides subdomain functionality:

  1. Configure DNS: Point your subdomain to your server
  2. Create Domain: Add the subdomain in WEMAZU and map a branch to it
  3. Deploy: Deploy your project to the subdomain

⚠️ Note: WEMAZU does not automatically provision subdomains or create any default domains. You configure domains and branch mappings yourself.

Custom Domains

Adding a Custom Domain

Step 1: Prepare Your Domain

Ensure you have:

  • ✅ Domain registered with a registrar
  • ✅ DNS access to configure DNS records
  • ✅ Server ready to host your application

Step 2: Configure DNS

See DNS Configuration section below.

Step 3: Add Domain in WEMAZU

  1. Go to Project → Domains
  2. Click "Add Domain"
  3. Enter your domain name
  4. Select your server
  5. Enter deploy path
  6. Save

Step 4: Verify DNS

Wait for DNS propagation (can take up to 48 hours, usually much faster), then verify:

  • Domain resolves to your server IP
  • SSL certificate is provisioned (if using HTTPS)

Domain Validation

WEMAZU does not currently validate domain ownership. You are responsible for:

  • ✅ Ensuring domain points to correct server
  • ✅ Configuring DNS correctly
  • ✅ Managing SSL certificates (if needed)

DNS Configuration

DNS Requirements

For your domain to work with WEMAZU, you need to configure DNS records:

Option 1: A Record (Direct IP)

Point your domain directly to your server's IP address:

Type: A
Name: @ (or your subdomain)
Value: your-server-ip (your server IP address)
TTL: 3600

Example:

example.com → your-server-ip
staging.example.com → your-server-ip

Option 2: CNAME Record (Subdomain)

Point a subdomain to another domain:

Type: CNAME
Name: staging
Value: example.com
TTL: 3600

Example:

staging.example.com → example.com

DNS Propagation

Typical Timeline:

  • ✅ Immediate: Sometimes updates are instant
  • ⏱️ 5-15 minutes: Most common
  • ⏱️ Up to 48 hours: Maximum (rare)

Check DNS Propagation:

Common DNS Issues

"Domain not resolving"

Problem: Domain does not resolve to your server.

Check:

  1. DNS records are correct
  2. DNS has propagated (wait up to 48 hours)
  3. Server is accessible from internet
  4. Firewall allows connections

"SSL certificate not working"

Problem: HTTPS does not work.

Note: WEMAZU does not automatically provision SSL certificates. You must:

  • Configure SSL on your server
  • Use Let's Encrypt or another certificate authority
  • Configure your web server (Apache/Nginx) for HTTPS

Domain Switching

What is Domain Switching?

Domain switching refers to changing which domain is used for a project, or changing the deploy path for a domain.

Changing Domain Configuration

Update Domain Settings

  1. Go to Project → Domains
  2. Click "Edit" on the domain
  3. Modify:
    • Domain name (if DNS is updated)
    • Server (if moving to different server)
    • Deploy path (if changing location)
    • Branch configurations
  4. Save changes

What Happens During Switch

If changing deploy path:

  • ✅ New deployments go to new path
  • ❌ Old files remain in old path (not deleted)
  • ⚠️ You may need to manually clean up old path

If changing server:

  • ✅ New deployments go to new server
  • ❌ Old files remain on old server
  • ⚠️ You must update DNS to point to new server

If changing domain name:

  • ✅ Domain record is updated in WEMAZU
  • ⚠️ You must update DNS records
  • ⚠️ Old domain may still work if DNS not updated

Changing Which Branch Deploys to a Domain

To change which branch is deployed to a domain (or path):

  1. Edit the domain (or the domain-branch row):

    • Change the Branch to another branch (from the list we read from GitHub)
    • Optionally change server or deploy path
    • Save

  2. Deploy:

    • Trigger a new deployment; the new branch is deployed to that domain/path

Best Practices for Domain Switching

  1. Test First: Test domain changes in a non-production environment
  2. Update DNS Gradually: Use low TTL before switching, then increase after
  3. Monitor: Watch logs and deployment status after switching
  4. Backup: Backup current deployment before switching
  5. Document: Document domain configurations for your team

Domain Status Management

Understanding Domain Status

Domain status reflects the state of the last deployment:

Status Flow:

pending → deploying → active
                  ↓
                error

Status Meanings

  • pending: Domain created but no deployment yet
  • deploying: Deployment in progress
  • active: Last deployment succeeded
  • error: Last deployment failed
  • failed: Domain configuration error

Updating Domain Status

Domain status is automatically updated during deployments:

During Deployment:

  • Status automatically updates to deploying when deployment starts
  • After successful deployment, status changes to active
  • After failed deployment, status changes to error

Manual Status Updates

You can manually update domain status if needed (via API or database), but this is typically not necessary as WEMAZU manages status automatically.

Multiple Domains per Project

Why Multiple Domains?

You can have multiple domains for the same project, each with one or more branch mappings:

Use Cases:

  • Different targets (e.g. one domain for develop, another for main)
  • Different regions (us.example.com, eu.example.com)
  • Different features (api.example.com, app.example.com)
  • A/B testing (variant-a.example.com, variant-b.example.com)

Configuration Example

Project: My Web App
├── Domain 1: staging.example.com
│   └── Branch: develop → Server A → /var/www/staging
├── Domain 2: example.com
│   └── Branch: main → Server B → /var/www/production
└── Domain 3: api.example.com
    └── Branch: main → Server B → /var/www/api

Primary Domain

You can mark one domain as primary:

  • ✅ Primary domain appears first in lists
  • ✅ Used as default in some operations
  • ✅ Only one primary per project

Setting Primary:

  1. Go to Project → Domains
  2. Click "Edit" on domain
  3. Check "Is Primary"
  4. Save

Troubleshooting

"Domain not found"

Problem: Domain does not appear in project.

Check:

  1. Domain is linked to correct project
  2. You have access to the project
  3. Domain was not deleted

Solution:

  1. Verify project ID matches
  2. Check that the domain is linked to the correct project
  3. Recreate domain if needed

"Deploy path not found"

Problem: Deployment fails because path does not exist.

Check:

  1. Path exists on server
  2. Path is absolute (starts with /)
  3. User has permissions to path

Solution:

  1. SSH into server and verify path: ls -la /var/www/html
  2. Create path if missing: mkdir -p /var/www/html
  3. Set permissions: chmod 755 /var/www/html

"DNS not resolving"

Problem: Domain does not resolve to server.

Check:

  1. DNS records are correct
  2. DNS has propagated
  3. Server is accessible

Solution:

  1. Verify DNS: dig example.com
  2. Check server firewall
  3. Wait for DNS propagation (up to 48 hours)

"Multiple domains conflicting"

Problem: Multiple domains point to same path, causing conflicts.

Solution:

  • Use different deploy paths for each domain
  • Or use different servers
  • Or deploy different branches to same path (not recommended)

Next Steps: