Quickstart

This guide walks you through your first deployment on Reoclo. You’ll install the GitHub App, add a server, create an application, and deploy. The entire process takes under 10 minutes.

Prerequisites

Before you start, make sure you have:

• A GitHub account with admin access to at least one repository
• A Linux server with Docker, git, and curl installed
• The ability to run commands on the server (to install the Runner agent)

Step 1: Get Your Account

Your organization is provisioned by the Reoclo team during onboarding. Once your account is set up, log in at app.reoclo.com with the credentials provided by your administrator.

If you belong to multiple organizations, you’ll see an organization picker after login. Select the organization you want to work in.

Step 2: Install the GitHub App

Reoclo uses a GitHub App to receive push webhooks and generate short-lived clone tokens. No long-lived credentials are stored.

1. Go to Settings → Integrations in the dashboard.
2. Click Install GitHub App.
3. You’ll be redirected to GitHub. Select the repositories you want to deploy. You can choose all repositories or specific ones.
4. Click Install & Authorize.

Reoclo will now receive push events from the selected repositories. When you push to a configured branch, Reoclo will automatically trigger a deployment.

Note

The GitHub App generates short-lived tokens to clone private repositories during deployments. Tokens are never stored. They’re generated on-demand and discarded after use.

Step 3: Add a Server

Servers are the deployment targets. Reoclo uses a Runner agent installed on your server that connects outbound to Reoclo via WebSocket. No inbound ports are required.

1. Go to Servers → Add Server in the dashboard.
2. Provide a Name for the server.
3. Click Generate Registration Token.
4. Copy the install command and run it on your server:

curl -fsSL https://get.reoclo.com/install.sh | bash -s -- <your-token>

The install script will:

• Download the Runner binary
• Install a systemd service (reoclo-runner.service)
• Register the Runner with Reoclo via WebSocket

Once the Runner connects, the server status will change to ACTIVE.

Tip

The Runner maintains a persistent WebSocket connection to Reoclo. If the connection drops, the Runner will automatically reconnect. If the server goes offline for more than 3 health check cycles, the status will change to UNREACHABLE.

Step 4: Create an Application

Applications map a GitHub repository, branch, and Dockerfile to a server. They also include runtime configuration like environment variables, port mappings, and health check paths.

1. Go to Applications → New in the dashboard.
2. Select the Repository you want to deploy. Only repositories linked via the GitHub App will appear.
3. Select the Branch to deploy (e.g., main or production).
4. Select the Server to deploy to.
5. Configure the application:
   • Dockerfile Path: Path to the Dockerfile in your repository. Defaults to ./Dockerfile.
   • Container Port: The port your application listens on inside the container (e.g., 3000).
   • Health Check Path: The HTTP path to poll for health checks (e.g., /health or /). Reoclo will curl this path after starting the container.
   • Environment Variables: Add any environment variables your application needs. These are encrypted at rest and injected into the container at runtime.
6. Click Create Application.

Your application is now ready to deploy.

Note

Environment variables are encrypted at rest. They’re decrypted only during deployment and never logged.

Step 5: Deploy

You can deploy manually or automatically on git push.

Manual Deploy

1. Go to Applications in the dashboard.
2. Click on your application.
3. Click Deploy.

Reoclo will schedule the deployment and run the pipeline on your server.

Auto-Deploy on Git Push

If you want deployments to trigger automatically when you push to the configured branch:

1. Go to your application’s detail page.
2. Enable Auto-Deploy in the settings.
3. Push to the configured branch.

Reoclo will receive the push webhook from GitHub and trigger a deployment automatically.

Step 6: Monitor the Deployment

The deployment will go through the following states:

• PENDING: Scheduled, waiting for execution.
• RUNNING: The deployment pipeline is executing on your server.
• SUCCEEDED: The deployment completed successfully. The new container is running.
• FAILED: The deployment failed. The old container was restarted (if it existed).

You can view deployment logs in the dashboard. Click on a deployment to see the full log output.

What Happens During Deployment

The deployment pipeline runs on your server:

1. Precheck: Verify git, docker, and curl are installed.
2. Clone: Securely clone the repo onto the target server using a short-lived token.
3. Build: Run docker build directly on the target server. Images are built locally. No central registry.
4. Deploy: Stop the existing container (if any), start the new one with environment variables. Blue-green swap within the same host.
5. Health Check: Poll the configured health check path via curl on the server. Retry up to 10 times with exponential backoff.
6. Cleanup/Rollback: On success, remove the old container. On failure, restart the old container and mark the deployment FAILED.

All builds happen on your server. Images never leave the target host.

Caution

If the health check fails, Reoclo will restart the old container (if it existed) and mark the deployment FAILED. Check the deployment logs to see what went wrong.

What’s Next

You’ve deployed your first application on Reoclo. Here’s what to explore next:

• Core Concepts: Understand organizations, servers, applications, and deployments in depth
• Servers Overview: Learn about server lifecycle, health monitoring, and connection types
• Deployments Overview: Understand the deployment pipeline and rollback behavior
• Deployment Configuration: Configure environment variables, health checks, and Docker build options
• Security: Learn about encryption, access control, and security best practices

If you run into issues, check the deployment logs in the dashboard or contact support.