Domain Management - DeployHub

Overview

Every DeployHub project can be accessed via a subdomain or a custom domain. Subdomains are automatically generated during project creation and can be updated at any time.

Domain Structure

Projects support two types of domains:

Subdomain

Automatically generated: {name}-{random}.deployhub.online

Custom Domain

Your own domain: www.example.com

Get Project Domains

GET /api/projects/:id/domains

Retrieve domain configuration for a project.

Authentication Required: Yes (JWT) Path Parameters:

string

required

Project ID (MongoDB ObjectId)

Response:

{
  "success": true,
  "project": {
    "_id": "507f1f77bcf86cd799439011",
    "subdomain": "my-website-a3f5k2",
    "hascustomDomain": false,
    "customDomain": null,
    "plan": "free"
  }
}

With Custom Domain:

{
  "success": true,
  "project": {
    "_id": "507f1f77bcf86cd799439011",
    "subdomain": "my-website-a3f5k2",
    "hascustomDomain": true,
    "customDomain": "www.example.com",
    "plan": "pro"
  }
}

Subdomain Generation

Subdomains are automatically generated during project creation using this algorithm:

Generation Logic

const generateUniqueName = async (name) => {
  let attempts = 0;
  while (attempts < 20) {
    const uniqueName = Math.random().toString(36).substring(2, 8);
    const subdomain = `${name.toLowerCase()}-${uniqueName}`;

    const existingDomain = await Model.Binding.findOne({ subdomain });
    if (!existingDomain) {
      const binding = new Model.Binding({
        project: projectId,
        subdomain: subdomain,
        port: projectinternalPort
      });
      await binding.save({ validateBeforeSave: false });
      return binding;
    }
    attempts++;
  }
  throw new Error("Could not generate unique subdomain after 20 attempts");
};

Subdomain Format

string

Format: {project-name}-{6-char-random}

Project name is converted to lowercase
Random string is 6 characters (base-36: 0-9, a-z)
Up to 20 attempts to ensure uniqueness

Example: my-website-a3f5k2

Full URL

The complete domain is: {subdomain}.deployhub.online Example: https://my-website-a3f5k2.deployhub.online

Update Subdomain

PATCH /api/projects/:id/domains/subdomain

Change the subdomain for a project. This triggers a container rebuild.

Authentication Required: Yes (JWT) Request Body:

string

required

New subdomain (without .deployhub.online)Validation: Must match pattern /^[a-z0-9-]{3,40}$/

Only lowercase letters, numbers, and hyphens
Length: 3-40 characters

Example Request:

{
  "subdomain": "my-awesome-site"
}

Response:

{
  "success": true,
  "subdomain": "my-awesome-site",
  "message": "Subdomain updated. Project is restarting."
}

Subdomain Validation

if (!subdomain || !/^[a-z0-9-]{3,40}$/.test(subdomain)) {
  return res.status(400).json({
    success: false,
    message: 'Invalid subdomain. Use lowercase letters, numbers, hyphens (3-40 chars).',
  });
}

Valid Examples:

my-site
production-app-2024
web-app-v2
my-project

Invalid Examples:

My-Site (uppercase not allowed)
my_site (underscores not allowed)
ab (too short, minimum 3 characters)
my.site (dots not allowed)

Uniqueness Check

const existing = await Model.Project.findOne({
  subdomain,
  _id: { $ne: req.params.id },
  status: { $ne: 'deleted' },
}).select('_id').lean();

if (existing) {
  return res.status(409).json({
    success: false,
    message: 'This subdomain is already taken. Please choose another.',
  });
}

The uniqueness check excludes the current project and deleted projects.

Subdomain Update Process

When updating a subdomain, several operations occur:

1. Update Project Status

project.subdomain = subdomain;
project.status = "building";
await project.save({ validateBeforeSave: false });

The project status is set to "building" during the subdomain transition.

2. Update Binding

const allocation = await Model.Binding.findOne({project: project._id});
allocation.subdomain = subdomain;
await allocation.save({validateBeforeSave: false});

The Binding model tracks the port allocation for the subdomain.

3. Update Redis Cache

// Remove old subdomain cache
await redisclient.del(`subdomain:${data.oldcontainername}`);

// Create new subdomain cache
await redisclient.hset(`subdomain:${project.subdomain}`, {
  port: allocation.port,
  projectId: project._id.toString(),
  plan: project.plan
});

Redis is used for fast subdomain-to-project routing.

4. Queue Container Rebuild

const data = {
  projectId: project._id,
  oldcontainername: project.subdomain,  // Before update
  newcontainername: subdomain            // After update
};

await recreateContainer.add('deployhub-recreate-container', data);

A worker recreates the Docker container with the new subdomain.

Binding Model

The Binding model manages domain-to-port mappings:

{
  project: ObjectId,        // Reference to Project
  subdomain: String,        // Subdomain (indexed)
  port: String,            // Internal port
  customDomain: String     // Optional custom domain
}

Index: subdomain field is indexed for fast lookups

Port Allocation

For static projects:

projectinternalPort = 80

For Node.js projects:

projectinternalPort = port  // User-specified port

Custom Domains

Custom domains are tracked in the project model:

hascustomDomain: {
  type: Boolean,
  default: false
},
customDomain: {
  type: String
}

Custom domain configuration endpoints are not shown in the provided source code. Custom domain setup may require additional DNS configuration and SSL certificate generation.

Redis Caching Strategy

Subdomains are cached in Redis for fast request routing: Key Format: subdomain:{subdomain-name} Cached Data:

{
  port: "80",
  projectId: "507f1f77bcf86cd799439011",
  plan: "free"
}

This allows the reverse proxy to quickly determine which container to route requests to without querying the database.

Example: Update Subdomain

const updateSubdomain = async (projectId, newSubdomain) => {
  const response = await fetch(
    `/api/projects/${projectId}/domains/subdomain`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        subdomain: newSubdomain
      })
    }
  );
  
  const data = await response.json();
  
  if (data.success) {
    console.log(`Subdomain updated to: ${data.subdomain}`);
    console.log('Container is being rebuilt...');
    
    // Poll for status
    pollProjectStatus(projectId);
  } else {
    console.error(`Error: ${data.message}`);
  }
};

const pollProjectStatus = async (projectId) => {
  const response = await fetch(`/api/projects/${projectId}/overview`);
  const { project } = await response.json();
  
  if (project.status === 'building') {
    console.log('Still rebuilding...');
    setTimeout(() => pollProjectStatus(projectId), 5000);
  } else if (project.status === 'live') {
    console.log(`Project is live at: ${project.domain}`);
  }
};

Error Responses

400 Bad Request - Invalid Format

{
  "success": false,
  "message": "Invalid subdomain. Use lowercase letters, numbers, hyphens (3-40 chars)."
}

404 Not Found

{
  "success": false,
  "message": "Project not found"
}

409 Conflict

{
  "success": false,
  "message": "This subdomain is already taken. Please choose another."
}

500 Server Error

{
  "success": false,
  "message": "Server error"
}

Security Considerations

Ownership Verification

All domain operations verify that the authenticated user owns the project

Uniqueness Enforcement

Subdomain uniqueness is enforced at the database level with indexed queries

Status Filtering

Deleted projects are excluded from subdomain availability checks

Redis Sync

Redis cache is updated atomically with database changes

Domain Display Logic

When displaying a project’s domain, use this logic:

const domain = project.hascustomDomain && project.customDomain
  ? project.customDomain
  : `${project.subdomain}.deployhub.online`;

This ensures custom domains take precedence when configured.

​Overview

​Domain Structure

Subdomain

Custom Domain

​Get Project Domains

GET /api/projects/:id/domains

​Subdomain Generation

​Generation Logic

​Subdomain Format

​Full URL

​Update Subdomain

PATCH /api/projects/:id/domains/subdomain

​Subdomain Validation

​Uniqueness Check

​Subdomain Update Process

​1. Update Project Status

​2. Update Binding

​3. Update Redis Cache

​4. Queue Container Rebuild

​Binding Model

​Port Allocation

​Custom Domains

​Redis Caching Strategy

​Example: Update Subdomain

​Error Responses

​400 Bad Request - Invalid Format

​404 Not Found

​409 Conflict

​500 Server Error

​Security Considerations

Ownership Verification

Uniqueness Enforcement

Status Filtering

Redis Sync

​Domain Display Logic

Overview

Domain Structure

Get Project Domains

Subdomain Generation

Generation Logic

Subdomain Format

Full URL

Update Subdomain

Subdomain Validation

Uniqueness Check

Subdomain Update Process

1. Update Project Status

2. Update Binding

3. Update Redis Cache

4. Queue Container Rebuild

Binding Model

Port Allocation

Custom Domains

Redis Caching Strategy

Example: Update Subdomain

Error Responses

400 Bad Request - Invalid Format

404 Not Found

409 Conflict

500 Server Error

Security Considerations

Domain Display Logic