Quick Start Guide
Follow this step-by-step tutorial to go from creating your Devpilot account to running your first deployment.
Quick Start Guide
This guide walks you through deploying an application on Devpilot end-to-end: creating your account, making a workspace, adding a server, creating a project and app, and then running the deployment wizard against a Git repository.
This tutorial assumes you have a GitHub, GitLab, or Bitbucket repository with a deployable application. If you do not have one, fork a sample project on your Git provider and follow along with it.
Prerequisites
Before you begin, make sure you have:
- An email address for registration, or a Google or GitHub account for social login
- A source code repository on GitHub, GitLab, or Bitbucket
- Either credentials for a supported cloud provider (AWS, Azure, GCP, DigitalOcean, or Vultr) if you want Devpilot to provision a new server, or SSH access to an existing server you want to connect
The complete walkthrough
Create your Devpilot account
Open the Devpilot registration page and sign up using one of the following:
- Email and password — Enter your first name, last name, email, and a password that meets the strength requirements, then accept the Terms of Service and Privacy Policy.
- Google — Click Google in the social sign-in area and authorize Devpilot.
- GitHub — Click GitHub in the social sign-in area and authorize Devpilot.
After registration you are sent to the two-factor authentication setup flow, which is mandatory. Scan the QR code with your authenticator app, enter the six-digit code, and store the backup codes that are shown.
For a detailed walkthrough of registration, 2FA setup, and profile configuration, see Account Setup.
Expected outcome: You land on the dashboard at /dashboard after completing 2FA setup.
Create a workspace
A workspace is the top-level container for your servers, projects, apps, and team members.
- Open Workspaces from the dashboard sidebar.
- Click New Workspace.
- Enter a Workspace Name (for example, "Acme Corp" or "Personal Projects"). Optionally upload a Logo.
- Click Save.
Devpilot creates the workspace and takes you to the workspace overview page.
Expected outcome: Your new workspace appears in the workspaces list and opens to its dashboard.
Add a server to the workspace
You need at least one server to deploy apps onto. Open Servers inside your workspace. You have two options:
Devpilot can provision a new virtual machine on a supported cloud provider:
- On the Servers page, open the provisioning action.
- Choose a supported cloud provider: AWS, Azure, GCP, DigitalOcean, or Vultr. (Hetzner, Linode, and MTN Cloud are coming soon.)
- If you have not connected credentials for this provider yet, add them through the workspace integrations so Devpilot can call the provider's API.
- Pick a region, instance type, and image.
- Give the server a name and start provisioning.
Devpilot tracks provisioning step-by-step. You can watch progress and read logs from the provision detail page.
Provisioning time depends on the provider and size. A small droplet or VM typically takes a couple of minutes.
If you already have a Linux server, connect it over SSH:
- On the Servers page, open the create server action.
- Enter the server name, host, and port (default
22). - Enter the username used to connect.
- Choose an authentication method:
- Private key — paste your key or upload a file
- Generated key — let Devpilot generate a new key pair
- Password
- Save the server.
Devpilot tests the SSH connection and begins installing its management agent.
Expected outcome: Your server appears in the server list. When the connection status is healthy and provisioning (if applicable) is complete, the server is ready for deployments.
Create a project
Projects group related apps inside a workspace.
- Open Projects inside your workspace.
- Click New Project.
- Enter a Project name and optionally upload a logo.
- Click Save.
Expected outcome: The new project appears in the list and opens to its detail page, ready for you to add apps.
Create an app
An app represents a single deployable unit inside a project. It is tied to a platform (such as Laravel, Node-based frameworks, or vanilla PHP/JavaScript) and a server.
- Inside your project, click Create New App.
- Enter an app Name.
- Choose a Platform — for example Laravel, Vanilla PHP, Vanilla JavaScript, Nuxt, React, or Vue.
- Choose the Server where this app will run (one of the servers from the previous step).
- Pick a Status (Active or Inactive).
- Save the app.
Repository, branch, build commands, environment variables, and the pipeline are configured during deployment, not on the app itself. The app is the target; the deployment wizard supplies the source and the commands.
Expected outcome: The app appears inside the project with a summary card showing its platform and server.
Run your first deployment
Deployments are created through a guided wizard that scans a repository and builds a pipeline for you.
- Open Deployments inside your workspace and start a New Deployment.
- Repository — Paste the HTTPS or SSH URL of the GitHub, GitLab, or Bitbucket repository you want to deploy, and pick a branch.
- Scanning — Devpilot inspects the repository and detects the framework, runtime, and likely build steps.
- Configure — Review the detected build configuration and override anything you want to change.
- Server — Select the project, app, and server this deployment targets. If the selected server is missing a required runtime, Devpilot surfaces a preflight banner so you can install it.
- Environment — Provide values for any environment variables the wizard detected.
- Pipeline — Review the generated pipeline of hooks across the five stages: Pre Execution, Pre Source Control, Post Source Control, Post Setup, and Post Release. Reorder, toggle, or edit hooks to match your app.
- Review — Confirm the plan and launch the deployment.
Devpilot runs the pipeline on the target server. The deployment detail page streams console output and shows each step's status in real time.
Environment variables often hold secrets such as API keys and database passwords. Double-check that you are entering values for the correct app and environment before launching.
Expected outcome: The deployment moves through Pending and Processing to Completed. The app is running on the server, and the deployment record captures the commit, logs, duration, and hooks that ran.
What to do next
With a successful deployment in place, explore the rest of Devpilot:
- Trigger more deployments — Run the wizard again to redeploy the latest commit, deploy a different branch, or tweak the pipeline.
- Customize hooks — Adjust pipeline hooks on the app so future deployments run exactly the commands you need.
- Enable monitoring — Turn on monitoring for your server to collect CPU, memory, and disk metrics.
- Invite teammates — Add members to the workspace and assign them the Owner, Admin, or Member role. See Key Concepts for what each role can do.
- Use the web terminal — Open an in-browser terminal on your server when you need to troubleshoot directly.
Troubleshooting
If a deployment fails, start with the deployment logs — they capture the full output of every hook. Common issues to check:
- Missing runtime on the server — The preflight banner in the wizard flags this before you launch. Install or upgrade the runtime on the server and retry.
- Pipeline command errors — Make sure the commands in the pipeline match how the project is built and started.
- Environment variables — Confirm that every variable your app needs has a value for this deployment.
- Repository access — Ensure the workspace has the correct source control integration connected and that it can read the repository and branch.
- Server connectivity — Check that the target server's connection status is healthy.
If the deployment is in progress, you can also cancel it from the deployment detail page and start a new one once you have the fix.
Getting Started with Devpilot
Learn what Devpilot is, who it's built for, and how to navigate this documentation to get the most out of the platform.
Key Concepts
Understand the core building blocks of Devpilot — workspaces, projects, apps, servers, deployments, pipelines, hooks, integrations, and roles — and how they relate to each other.