Deploy Manager User Guide: Setup & Use

This guide explains how to set up and use Deploy Manager, a tool for automating software deployments. You will learn the core concepts, how to configure your first deployment, and how to troubleshoot common issues. The guide is written for users who have basic familiarity with web servers and version control.

What is Deploy Manager?

Deploy Manager is a web-based application that helps teams release new versions of their software to servers. Instead of manually copying files or running commands on each server, Deploy Manager lets you define a deployment process once and then trigger it with a single click or automatically after a build. It typically integrates with Git repositories, so you can deploy a specific branch or tag. The tool tracks each release, shows you what changed, and can roll back to a previous version if something goes wrong.

Key Concepts

Before you start, you need to understand a few terms that Deploy Manager uses:

• Project: A project represents a single application or service you want to deploy. It contains settings like the repository URL, the servers to deploy to, and the deployment steps.
• Environment: An environment is a target where the code runs, such as staging, production, or test. Each project can have multiple environments, and each environment has its own configuration (server addresses, environment variables, etc.).
• Deployment: A deployment is a single run of your deployment process to a specific environment. It has a status (pending, running, succeeded, failed) and a log of what happened.
• Deployment Step: A step is one action in your deployment process, like run composer install or restart php-fpm. Steps run in order, and you can define conditions for when they run.

Setting Up Your First Project

To create a project, log in to Deploy Manager and click the New Project button. You will be asked for:

1. Project name: A human-readable name, e.g., MyApp.
2. Repository URL: The Git URL (HTTPS or SSH) of your code repository.
3. Branch/tag to deploy: The default branch you want to deploy (e.g., main). You can override this per deployment.
4. Deployment path: The directory on the server where the code should be placed (e.g., /var/www/myapp).

After saving the project, you need to add at least one environment. Click Add Environment and give it a name (e.g., production). Then, under the environment settings, you will add the server(s) where the code will be deployed. You typically provide an SSH connection string (user@host) and a path on that server. You can also set environment-specific variables, like API keys or database URLs, which will be available during the deployment steps.

Defining Deployment Steps

The heart of Deploy Manager is the deployment process. In the project settings, you can define a list of steps that run in order. Each step has a type, such as:

• Run command: Execute a shell command on the server (e.g., composer install --no-dev).
• Upload files: Copy local files or directories to the server.
• Symlink: Create a symbolic link to point the current release to the latest version.
• Notify: Send a Slack or email notification about the deployment status.

For example, a typical deployment for a PHP app might look like:

1. Upload the code to a new release directory (e.g., /var/www/releases/20240101-1200).
2. Run composer install --no-dev --prefer-dist.
3. Run database migrations: php artisan migrate --force.
4. Create a symlink from /var/www/myapp to the new release.
5. Restart the web server: sudo systemctl restart php-fpm.

You can also add conditions to steps, like only run the migration step if the environment is production. This is done with simple expressions like environment == 'production'.

Running a Deployment

Once your project and steps are configured, you can start a deployment. On the project dashboard, click Deploy and select the environment. You can also specify a different branch or tag to deploy. The tool will then:

1. Fetch the latest code from the repository.
2. Run each step in order on the server(s).
3. Show a live log of each step’s output.
4. Mark the deployment as succeeded or failed.

If a step fails, the deployment stops, and you can view the log to see what went wrong. You can also roll back to a previous successful deployment by clicking Rollback on that deployment. Rollback typically re-runs the previous release’s steps (like re-symlinking to the old release).

Common Problems and Solutions

Here are issues you might encounter and how to fix them:

• SSH connection refused: Check that the server’s IP and port are correct, and that your SSH key is added to the server’s authorized_keys file. Also verify the user has permission to access the deployment path.
• Permission denied when writing files: The deployment user needs write access to the deployment directory. Use sudo chown -R deployuser:www-data /var/www/myapp on the server.
• Command not found: The SSH session may not have the same PATH as your interactive shell. Use the full path to the command (e.g., /usr/local/bin/php) or add a step to load the environment: source ~/.bashrc.
• Deployment hangs: A step may be waiting for input (like a password). Ensure your commands use --no-interaction flags where available, or set environment variables to avoid prompts.
• Rollback fails: If the rollback step tries to run commands that depend on the new code (like migrations), it may fail. Design your rollback steps to be independent of the code version.

Frequently Asked Questions

Can I deploy to multiple servers at once?

Yes, Deploy Manager supports multiple servers per environment. When you add more than one server, the deployment runs the steps on each server sequentially (or in parallel if you enable that option). This is useful for load-balanced setups.

How do I set environment variables for my app?

You can define environment variables in the environment settings. These are injected into the deployment process as shell variables, so your steps can use them (e.g., DATABASE_URL=$DATABASE_URL). They are also written to a .env file on the server if you have a step that does that.

Can I deploy automatically after a Git push?

Yes, Deploy Manager can integrate with your Git repository’s webhooks. You set up a webhook URL from Deploy Manager in your Git provider (like GitHub or GitLab) to trigger a deployment whenever a push occurs to a specific branch. This enables continuous deployment.

What happens if a deployment fails halfway?

The deployment stops at the failed step. The server may be in an inconsistent state (e.g., new code uploaded but migration not run). You can manually run the remaining steps by editing the deployment and re-running it, or you can roll back to the previous successful deployment to restore the old code.

Is Deploy Manager free?

Deploy Manager is an open-source tool, so it is free to use. However, you need to host it yourself on a server. There are also commercial hosted alternatives if you prefer not to manage it.

How do I update Deploy Manager itself?

To update, you pull the latest changes from the Deploy Manager repository and run any database migrations. The exact steps depend on how you installed it (e.g., via Git or Docker). Always back up your data before updating.

Alternatives and Comparisons

Deploy Manager is not the only deployment tool. Common alternatives include:

• Capistrano: A command-line tool written in Ruby that uses SSH to deploy. It is very flexible but requires more manual setup.
• Deployer: A PHP-based tool similar to Capistrano, with a simpler syntax for defining tasks.
• Ansible: A general-purpose configuration management tool that can also handle deployments. It uses YAML playbooks.
• CI/CD platforms (GitHub Actions, GitLab CI): These can deploy your code as part of a pipeline, but they are not specialized for deployment management (like rollbacks).

Deploy Manager stands out because it provides a web UI, a history of deployments, and one-click rollbacks, which are not built into most CI/CD tools.

Conclusion

Deploy Manager is a powerful tool that can save you time and reduce errors in your release process. Start with a simple project, test on a staging environment, and gradually add steps as you become comfortable. Always keep your deployment steps idempotent (safe to run multiple times) to avoid issues when retrying failed deployments.

Related

• How Long Can an Astronaut Work Outside on the Moon?
• Best Alternatives to Utility Portals for Electricity Tracking
• PostgreSQL Alternatives for AI Workloads: Top Options