ℹ️ About

ServUP is a lightweight, open-source, and easy-to-use deployment tool designed to simplify the process of deploying artifact from GitHub Actions to remote servers. It provides a simple and efficient way to manage your deployments, ensuring that your applications are always up-to-date and running.

📑 Index

• About
  • Index
  • Features
• Installation
  • Server Configuration
  • Repository Configuration
• Annexes
  • Iptables Support

✨ Features

ServUP uses SSH to securely transfer files from your GitHub Actions workflow to your remote server.

⚙️ Installation

In order to work with ServUP, you need to do some configuration on your server and your GitHub repository.

☁️ Server Configuration

Install ServUP on your server via the command-line with curl:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/S2009-dev/ServUP/main/tools/install.sh)"

This will create a servup user on your server and open a specific port for SSH connections (1424 by default).
Ensure that you've copied the ServUP SSH Key given at the end of installation.

If you have a firewall, make sure to open the port given at the end of installation.
You can trust only GitHub Actions IPs, they are listed in the actions section of the GitHub meta API.
We provide a script to help you configure your firewall if you are using iptables. See Iptables Support for more information.

📁 Repository Configuration

1. Add the following secrets to your GitHub repository:

• SSH_HOST: The IP address or domain name of your server.
• SSH_PORT: The port used by ServUP for SSH connections (default: 1424).
• SSH_PRIVATE_KEY: The private key of the servup user on your server.

2. Implement the ServUP Deployment workflow:
Add the following step to your workflow:

- name: ServUP Deployment
  uses: S2009-dev/ServUP@latest
  with:
    artifact: <ARTIFACT>
    run-id: ${{ github.run_id }}
    remote: /var/lib/servup/<REMOTE>
    deploy-cmd: <DEPLOY CMD>
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SSH_HOST: ${{ secrets.SSH_HOST }}
    SSH_PORT: ${{ secrets.SSH_PORT }}
    SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

Or if you want to use the development version:

- name: ServUP Deployment
  uses: S2009-dev/ServUP@latest
  with:
    artifact: <ARTIFACT>
    run-id: ${{ github.run_id }}
    remote: /var/lib/servup/<REMOTE>
    deploy-cmd: <DEPLOY CMD>
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SSH_HOST: ${{ secrets.SSH_HOST }}
    SSH_PORT: ${{ secrets.SSH_PORT }}
    SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

Replace <ARTIFACT>, <REMOTE> and <DEPLOY> with your own values.

• <ARTIFACT> is the name of the artifact generated by your workflow (ex: my-artifact).
  • ⚠️ Warning: Ensure that your workflow generates an artifact containing a zip file.
• <REMOTE> is the remote directory where the artifact will be uploaded (ex: my-remote).
  • ⚠️ Warning: The remote directory must be accessible by the servup user.
• <DEPLOY CMD> is the directory where the artifact will be deployed (ex: my-deploy).
  • ⚠️ Warning: The deploy command must be a valid command that can be executed by the servup user.
  • You can allow the servup user to execute the deploy command by creating and editing the /etc/sudoers.d/servup file.

🔧 Annexes

Here you will find additional tools and resources to help you use ServUP effectively.

🔥 Iptables Support

If you are using iptables as your firewall, you can use the following command to open the ServUP SSH port:

servup-firewall

Or if it's not working:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/S2009-dev/ServUP/main/tools/firewall.sh)"