Core Concepts

Reoclo is built around a few core objects: organizations, users, servers, applications, and deployments. Understanding these concepts will help you navigate the platform and design your deployment workflows.

Quick Reference

Concept	What It Is	Key Properties
Organization	Your company or team boundary	All resources scoped to an organization
User	Global identity	Email-based, can belong to multiple organizations
Role	Permission level	admin, manager, developer, viewer
Server	Deployment target	Runner agent connection, BYOS model
Application	Deployable unit	Maps repo + branch + Dockerfile to a server
Deployment	Execution record	PENDING → RUNNING → SUCCEEDED/FAILED
Repository	GitHub repo link	Connected via GitHub App, webhook-driven

Organizations

An organization represents your company or team boundary. All resources (servers, applications, deployments, users) are scoped to an organization. Your organization is provisioned by the Reoclo team during onboarding. You can belong to multiple organizations and switch between them in the dashboard.

Organizations are isolated from each other. A user in Organization A cannot access Organization B’s servers or deployments unless they have a role in Organization B.

Use Cases

• Single organization: One organization for your company. All teams share the same organization.
• Multiple organizations: One organization per client or project. Switch between organizations in the dashboard.
• Development/Staging/Production: One organization per environment. Isolate infrastructure and access control.

Tip

If you’re managing multiple clients or projects, create a separate organization for each. This keeps resources isolated and simplifies access control.

Users and Roles

Users are identified by email. A user can belong to multiple organizations with different roles.

When you log in, you’ll see an organization picker if you belong to multiple organizations. Select the organization you want to work in. The dashboard will show only resources scoped to that organization.

Roles

Roles determine what actions a user can perform within an organization:

Role	Permissions
Admin	Full control. Manage servers, applications, deployments, users, and organization settings.
Manager	Manage servers, applications, and deployments. Generate runner tokens. Cannot manage users or organization settings.
Developer	Deploy applications. View servers and deployments. Cannot manage infrastructure or users.
Viewer	Read-only access. View servers, applications, and deployments. Cannot deploy or modify resources.

Roles are assigned per-organization. A user can be an admin in one organization and a viewer in another.

Servers

Servers are the deployment targets. Reoclo follows a BYOS (Bring Your Own Server) model. You provide the server, Reoclo handles the deployments.

Servers are provider-agnostic. Any Linux server with Docker, git, and curl can be a deployment target. You can bring your own server (BYOS) from any provider, or connect cloud credentials (Hetzner, DigitalOcean, AWS, Vultr, Linode) for managed provisioning and power operations.

Connection

Servers connect to Reoclo via the Runner agent — a lightweight Node.js agent installed on your server. The agent makes an outbound WebSocket connection to Reoclo. Commands are relayed through this connection, so no inbound ports are required.

Server Lifecycle

Servers move through the following states:

State	Description
PROVISIONING	Initial state after creation. Transitions to ACTIVE after first successful health check.
ACTIVE	Server is reachable and accepting deployments.
UNREACHABLE	Runner agent disconnected. Automatically recovers to ACTIVE on reconnect.
DECOMMISSIONED	Soft delete. Cannot be modified or deployed to.

The runner agent maintains a WebSocket heartbeat. If the connection drops, the server is marked UNREACHABLE. When the agent reconnects, it returns to ACTIVE.

Caution

If a server is in UNREACHABLE state, deployments will fail. Check the server’s network connectivity and ensure Docker, git, and curl are installed.

Applications

Applications are deployable units. An application maps a GitHub repository, branch, and Dockerfile to a server. It also includes runtime configuration:

• Dockerfile Path: Path to the Dockerfile in your repository. Defaults to ./Dockerfile.
• Container Port: The port your application listens on inside the container.
• Health Check Path: The HTTP path to poll for health checks (e.g., /health or /).
• Environment Variables: Key-value pairs injected into the container at runtime. Encrypted at rest.

Applications are scoped to your organization. You can only deploy applications to servers within the same organization.

Auto-Deploy

If auto-deploy is enabled, Reoclo will automatically trigger a deployment when you push to the configured branch. The GitHub App sends a notification to Reoclo, which schedules a deployment.

If auto-deploy is disabled, you must trigger deployments manually from the dashboard.

Tip

Enable auto-deploy for staging environments. Keep it disabled for production and trigger deployments manually after testing.

Deployments

Deployments are execution records. When you trigger a deployment (manually or via git push), Reoclo creates a deployment record and executes the pipeline on your server.

Deployment States

Deployments move through the following states:

State	Description
PENDING	Queued, waiting for execution.
RUNNING	The deployment pipeline is running 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.

Deployment Pipeline

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.
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.

Note

If the health check fails, Reoclo will restart the old container (if it existed) and mark the deployment FAILED. This ensures your application stays online even if the new deployment is broken.

Rollback Behavior

Reoclo uses blue-green deployments within the same host. When a deployment starts:

1. The new container is started alongside the old one.
2. Health checks run against the new container.
3. If health checks pass, the old container is stopped and removed.
4. If health checks fail, the new container is stopped and the old container is restarted.

This ensures zero-downtime deployments and automatic rollback on failure.

Caution

Rollback only works if the old container still exists. If you manually delete the old container or if this is the first deployment, rollback is not possible.

Repositories

Repositories are GitHub repos linked to Reoclo via the GitHub App. When you install the GitHub App, Reoclo receives push webhooks from the selected repositories.

Reoclo does not store long-lived GitHub credentials. Instead, it generates short-lived tokens on-demand during deployments. Tokens are used to clone private repositories and are discarded after use.

Webhook Flow

1. You push to a configured branch.
2. GitHub sends a push webhook to Reoclo.
3. Reoclo verifies the webhook signature.
4. If auto-deploy is enabled for an application watching that branch, Reoclo schedules a deployment.
5. Reoclo executes the pipeline on your server.

Tip

You can view webhook delivery history in the GitHub App settings. If deployments aren’t triggering automatically, check the webhook logs for errors.

Next Steps

Now that you understand the core concepts, explore the following guides:

• 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 isolation

If you have questions, check the deployment logs in the dashboard or contact support.