docs-by-racso

Dropship

A simple CI/CD tool to deploy your code to a server.

Prerequisites

1. Apache and PHP 8.0 or higher.

2. Git. To install it, run:

    sudo apt-get install git
   

3. A GitHub account, and a personal access token with the repo scope. See here for more information, or click here to create a token.

Installation

1. Copy all the files in the project to a web-accessible folder in your server.

2. Set the owner of the Dropship folder and all its content to www-data (or the user your web server runs as), and its permissions to 750:

    sudo chown -R www-data:www-data /path/to/dropship
    sudo chmod -R 750 /path/to/dropship
   

3. Rename file example.config to config and edit it. Add an administrative access token:

    TOKEN=your_token_here
   

   Please use a password generator to generate a secure token. You can use Random.org to quickly generate one.

4. Rename file example.deploy.json to deploy.json.
5. In your web browser, navigate to the path where Dropship is installed. Log in with your access token.
6. After logging in, navigate to /check and validate that all checks pass.

Adding a repository: manual

These first steps will add a repository that you can update manually.

1. Edit the deploy.json file in your Dropship installation and add the following information:
   1. Add your GitHub user information: username and personal access token with repo scope.

   2. Add your repository information: repository URL, branch to deploy, and server path to deploy to. Use the examples in the file as reference.

      For now, ignore the secret value; you’ll use it later if you want to set up automatic deployment.

That’s it. You can now manually deploy your repository’s code. Go to the Manual deployment section for more information.

Adding a repository: automatic

These steps will automate the deployment of your code every time you push to your repository.

1. In the GitHub repository you want to deploy, go to Settings > Webhooks > Add webhook.
   1. In the Payload URL field, enter the URL of your Dropship installation, followed by /notify. For example: https://example.com/dropship/notify.
   2. Set the Content type to application/json.
   3. Set the Secret to a random string. Again, we suggest using Random.org to quickly generate one.
   4. Select the push event.
   5. Click Add webhook.
2. Edit the deploy.json file in your Dropship installation and add the Secret of your repository in the corresponding secret field.

That’s it. Every time you push to your repository, Dropship will automatically deploy the latest version of your code to your server.

Pro-tip: if you only want to use automatic deployment (no manual), you can remove the token field from the deploy.json file to disable login.

Manual deployment

Dropship includes a web interface to manually deploy your repository’s code. To manually deploy, follow these steps:

1. Log in to Dropship.
2. In the dashboard, you’ll see the repositories you have registered. Identify the repository you want to deploy.
3. In the box, enter the commit hash you want to deploy (e.g. af3719eba1628), or the name of the remote branch (e.g. origin/main).
4. Click Deploy. Dropship will deploy the code to your server.
5. After deploying, Dropship will show you the result of the deployment. If everything went well, you’ll see a success message. If something went wrong, you’ll see an error message.