Hub.ai

Introduction

Hub.ai is a platform designed to dramatically simplify the process of deploying web applications and services. By integrating directly with GitHub, Hub.ai allows you to go from a code repository to a live, running application hosted on a dedicated Virtual Machine (VM) in seconds. Our goal is to eliminate the complexities of infrastructure setup and management, allowing developers to focus purely on building and iterating.

Whether you need to quickly demo a new feature, test a pull request in an isolated environment, explore an open-source project without local setup hassles, or host a temporary application, Hub.ai provides the tools and infrastructure you need.

Core Concepts

Understanding these fundamental concepts will help you make the most of Hub.ai.

Git & GitHub Repositories

Git is a distributed version control system used for tracking changes in source code during software development. It allows multiple developers to collaborate efficiently.

A Git Repository (Repo) is a collection of files and folders tracked by Git, including the entire history of changes. GitHub is a popular web-based platform that provides hosting for Git repositories. It offers collaboration features like pull requests, issue tracking, and more.

Hub.ai leverages public GitHub repositories as the source for your deployments. When you provide a GitHub URL, Hub.ai clones (downloads) a copy of that repository's code to build and run your application.

Virtual Machines (VMs)

A Virtual Machine (VM) is a software-based emulation of a physical computer. It runs its own operating system (like Linux) and has virtualized resources allocated to it, such as CPU (processing power), RAM (memory), and disk storage. VMs provide isolated environments, meaning applications running in one VM generally do not interfere with others.

Hub.ai uses VMs to host your deployed applications. Each deployment runs within its own dedicated VM instance, ensuring isolation and providing predictable resources. You can manage these VMs, choosing different sizes based on your application's needs and budget.

Deployments

In the context of Hub.ai, a Deployment represents a specific instance of your application running on a VM, based on code from a particular GitHub repository (and potentially a specific branch or commit). It encompasses the entire process of taking the source code, setting up the environment, installing dependencies, building the application (if necessary), and running it on a provisioned VM.

You can have multiple deployments, even from the same repository (e.g., deploying different branches for testing), each running independently.

Getting Started

Sign In / Sign Up

To begin using Hub.ai, you need an account. Navigate to the Sign In / Sign Up page using the link in the header. You can create an account or sign in using your existing GitHub or Google account for seamless integration. (Note: Authentication is currently simulated for demonstration purposes).

Platform Navigation

Once logged in, the main navigation header provides access to the key sections of the platform:

• Home: The main dashboard providing an overview and quick access.
• Repos: Manage the GitHub repositories you've linked to Hub.ai for deployment.
• Deployments: View the status and details of your active and past application deployments.
• VMs: View and manage the underlying Virtual Machines hosting your deployments.
• Docs: (You are here) Access this documentation.
• Account: Manage your profile, connected accounts, preferences, billing, and affiliate status.

Deployment Workflow

Deploying an application on Hub.ai involves a few straightforward steps:

1. Tracking a Repository

1. Navigate to the Repos page.
2. In the "Add New Repository" section, paste the full HTTPS URL of the public GitHub repository you wish to deploy (e.g., https://github.com/user/repo-name).
3. Click "Track Repository". Hub.ai will verify the URL and add it to your list of tracked repositories. This doesn't deploy the application yet, it simply tells Hub.ai you're interested in this repo.

2. Initiating a Deployment

1. On the Repos page, find the repository you just tracked (or any other tracked repo) in the "Tracked Repositories" list.
2. Click the "Deploy" button associated with that repository.
3. (Future Feature): You might be prompted to select a branch, choose a VM type, or configure environment variables. Currently, it defaults to deploying the default branch (usually `main` or `master`) on a suitable VM.

3. The Deployment Process Explained

Once you initiate a deployment, Hub.ai performs the following steps automatically:

1. Queued: The deployment request is added to the queue.
2. VM Provisioning: Hub.ai selects an appropriate VM size (or uses one you specified) and ensures a VM instance is ready. This might involve starting an existing stopped VM or creating a new one if necessary.
3. Cloning Repository: The specified Git repository (and branch) is cloned onto the provisioned VM.
4. Environment Detection (Basic): Hub.ai attempts to detect the application's language and framework (e.g., Node.js, Python, static HTML) based on common project files (like package.json, requirements.txt, index.html).
5. Dependency Installation: Based on the detected environment, Hub.ai runs standard commands to install necessary dependencies (e.g., npm install, pip install -r requirements.txt).
6. Build Step (If Applicable): For some frameworks, a build step might be required (e.g., npm run build). Hub.ai attempts to run common build commands if detected.
7. Starting Application: Hub.ai runs standard commands to start the application (e.g., npm start, python app.py) or configures a web server for static files.
8. Health Check & Routing: The platform performs basic health checks to ensure the application started correctly and configures routing so the application is accessible via a unique URL.
9. Deployed: If all steps succeed, the deployment status changes to "Deployed" or "Running".

You can monitor the progress and view logs for these steps on the Deployments page by clicking "View Details" for the specific deployment.

4. Accessing Your Deployed Application

Once a deployment is successfully running:

1. Go to the Deployments page.
2. Find the relevant deployment entry.
3. Click "View Details".
4. The deployment details page will display the unique URL assigned to your running application (e.g., https://some-unique-id.hub.ai-app.com). Click this link to access your live application.

Managing Repositories

The Repos page is your central hub for managing the source code repositories Hub.ai can deploy.

• Adding Repos: Use the form to add any public GitHub repository URL.
• Viewing Repos: The list displays all repositories you are currently tracking.
• Deploying: Each listed repo has a "Deploy" button to quickly initiate a new deployment based on its default branch.
• Viewing Details: Clicking the repository name (e.g., user/repo-name) takes you to a page showing more details about the repository itself, including recent commits, branches, and associated deployments (currently simulated).
• Untracking (Future Feature): Functionality to remove a repository from your tracked list may be added later.

Managing Deployments

The Deployments page provides an overview of all your application instances.

Understanding Deployment Status

Deployments can have various statuses reflecting their current state:

• Queued: The deployment request has been received and is waiting for resources or its turn to start.
• Deploying: The deployment process (cloning, installing, starting) is actively in progress.
• Deployed / Running: The application has been successfully deployed and is currently running and accessible.
• Error / Failed: The deployment process encountered an error and could not complete successfully. Check the logs for details.
• Stopped: The underlying VM for this deployment has been stopped (see VM Management). The application is not running.
• Pending: An intermediate state, often waiting for VM provisioning or another prerequisite.

Viewing Deployment Details & Logs

Clicking "View Details" for any deployment provides more information:

• Source: The GitHub repository and branch used.
• Target VM: A link to the specific VM hosting this deployment.
• Timestamps: When the deployment was started and finished.
• Live URL: The URL to access the running application.
• Logs: A stream of output generated during the deployment process (cloning, installation, startup). This is crucial for diagnosing failures. (Currently simulated).
• Actions (Future): May include options to redeploy, restart the application without a full redeploy, or view resource usage.

Managing Virtual Machines (VMs)

Virtual Machines are the foundation upon which your deployments run. The VMs page allows you to view and manage these instances.

VM Types & Resources

Hub.ai offers several VM types, each providing different amounts of computational resources. Choosing the right type depends on your application's requirements and budget.

• vCPU (Virtual Central Processing Unit): Represents the processing power allocated to the VM. More vCPUs generally mean faster computation and ability to handle more concurrent requests.
• RAM (Random Access Memory): The working memory available to the VM's operating system and your application. Insufficient RAM can lead to slow performance or crashes.
• Disk: The persistent storage space available for the operating system, your application code, dependencies, and any data generated or stored by the application.
• Credits / Hour: The estimated cost to run this VM type for one hour, billed per minute of active runtime. See the Billing & Credits section for details.
• Note: These are estimated base costs. Adding optional resources like a GPU significantly increases credit consumption (see main page pricing examples or the Billing & Credits section).

Choosing the Right VM Type

• Start Small: For new projects or simple applications, start with a Micro or Small instance and monitor performance.
• Consider Memory Needs: Applications involving large datasets, complex frameworks, or many concurrent users often require more RAM.
• CPU for Computation: If your application performs heavy calculations or needs to process requests very quickly, consider a type with more vCPUs.
• Disk Space: Ensure the disk size is sufficient for your application, its dependencies, and any expected data storage.
• Cost vs. Performance: Balance your performance requirements with your budget. Larger instances cost more credits per hour.

VM Management Actions (Start/Stop/Monitor)

From the VMs list or the individual VM details page, you can perform actions:

• Start: Powers on a stopped VM. This makes any deployments hosted on it accessible again and resumes credit consumption.
• Stop: Powers off a running VM. This makes deployments on it inaccessible and stops credit consumption for the VM's runtime. This is useful for saving costs on development or infrequently used instances. The disk storage persists, so you can start it again later.
• Monitor (via Details Page): The VM details page provides information about status, IP addresses, resource allocation, and potentially links to more detailed monitoring tools (future feature).
• Delete (Future Feature): Permanently removes the VM and all associated data, including disk storage. This action is irreversible.

Viewing VM Details

Clicking "Manage" on a VM in the list takes you to its details page, showing:

• ID, Name, Status, Region
• IP Addresses (Public/Private, if applicable)
• Resource Allocation (CPU, Memory, Storage, OS)
• Creation Date
• Associated Deployments (Links to deployments running on this VM)
• Tags (User-defined labels for organization)
• (Future) Monitoring metrics, network settings, console access.

Creating Standalone VMs

While deployments typically create VMs automatically, you can also create standalone VMs via the "Create New VM" button on the VMs page. This allows you to provision a VM with a specific OS and size without immediately deploying an application to it. You might use this for custom setups, databases, or other services.

Account Management

The Account page provides several tabs for managing your profile and settings.

Profile Information

Update your display name. Your email address is linked to your sign-in provider (Google/GitHub) and cannot be changed directly here.

Connected Accounts

View the Google or GitHub accounts linked for sign-in. You can disconnect accounts, but you must maintain at least one connection method to be able to sign in.

Preferences

• Theme: Choose between available UI themes (currently Dark, Light planned).
• Notifications: Enable or disable email notifications for important account and billing events.

Affiliate Program

If you participate in the Hub.ai affiliate program:

• View your unique referral code and copy it to share.
• Track the total number of users referred.
• See your total earned commissions.
• View recent referral history and income charts (simulated data).

Security (Sign Out, Delete Account)

• Sign Out: Securely sign out of your Hub.ai session on the current device.
• Delete Account: Permanently delete your Hub.ai account and all associated data (repositories, deployments, VMs, billing info). This action is irreversible and requires confirmation.

Billing & Credits

Hub.ai operates on a flexible, pay-as-you-go credit system detailed in the Billing tab of your Account page.

The Credit System

• 1 Credit = $1.00 USD (subject to change).
• You purchase credits upfront.
• Running VM instances consume credits based on their type (CPU, RAM) and the duration they are active. Billing occurs per minute of runtime.
• Stopping a VM instance immediately stops credit consumption for that instance's runtime. Storage costs may apply separately in the future but are currently included.
• Your current credit balance is displayed prominently.

Topping Up Credits

• Select a predefined credit package ($10, $25, $50, $100) or enter a custom amount (minimum 10 credits).
• Click "Proceed to Checkout" to complete the purchase via our secure payment processor (simulated).
• Purchased credits are added to your balance immediately upon successful payment.

Monitoring Usage

• The Billing tab includes charts showing your credit usage over time (e.g., daily consumption).
• (Future) Detailed breakdowns of usage per VM or deployment may be available.

Billing History

A table displays a log of all transactions affecting your credit balance:

• Credit purchases (Top Ups).
• Credit deductions due to VM instance runtime.
• Timestamp, description, monetary amount (for purchases), credit change, and resulting balance for each entry.

Troubleshooting & FAQ

• My deployment failed, what should I do?

  Go to the Deployments page, click "View Details" for the failed deployment, and carefully examine the Logs section. Errors during cloning, dependency installation, or application startup are usually logged there. Check your repository for missing files, incorrect configurations, or code errors.

• Can I deploy private GitHub repositories?

  Currently, Hub.ai primarily supports deploying from public GitHub repositories. Private repository support may be added in the future.

• How do I update my deployed application?

  (Future Feature) Ideally, pushing changes to your tracked GitHub branch would automatically trigger a new deployment. Alternatively, a "Redeploy" button on the deployment details page might be available. Currently, you may need to initiate a new deployment manually.

• Why did my application stop working?

  Check if the VM hosting the deployment was stopped (either manually or potentially due to running out of credits - future feature). Check the deployment status and logs. Ensure your application code itself is stable.

• How do I connect to my VM directly (e.g., via SSH)?

  Direct VM access (like SSH) is not currently offered through the Hub.ai interface. The platform focuses on automated deployment and management based on your Git repository.