Hop3 Quick Start: Deploying Your First Application¶

This guide will walk you through deploying your first web application from scratch. We will create a simple Python Flask application, configure it for Hop3, and deploy it to your server.

By the end of this tutorial, you will have a live web application managed by Hop3.

Prerequisites¶

Before you begin, you must have the following:

1. A Server with Hop3 Installed: You need a server (or VM) with a fresh installation of Hop3. If you haven't done this yet, follow the Hop3 Installer Guide first.
2. The Hop3 CLI on Your Local Machine: The hop3 command-line tool should be installed locally. The installation guide covers setting up the development environment, which includes the CLI.

Step 1: Create a Sample Python Application¶

First, let's create a simple "Hello World" application using the Flask framework. On your local machine, create a new directory for your project.

mkdir hello-hop3
cd hello-hop3

Inside this directory, create two files: app.py and requirements.txt.

app.py¶

This file contains the code for our web application.

# app.py
import os
from flask import Flask

app = Flask(__name__)

# Hop3 will set the PORT environment variable to tell our app what port to listen on.
port = int(os.environ.get("PORT", 5000))

@app.route('/')
def hello_world():
    return '<h1>Hello, Hop3!</h1><p>Your Flask application is running.</p>'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=port)

requirements.txt¶

This file lists the Python dependencies our application needs. Hop3 installs them during the build.

# requirements.txt
Flask
gunicorn

Step 2: Configure the Application for Hop3¶

Now, we need to tell Hop3 how to build and run our application. We do this by creating a hop3.toml file in the root of our project directory.

Create the hop3.toml file with the following content:

# hop3.toml

# The [metadata] section is mandatory. It describes your application.
[metadata]
id = "hello-hop3"
version = "0.1.0"
title = "Hello Hop3 App"
author = "A Hop3 User"
description = "A simple Flask application to demonstrate Hop3 deployment."

# The [build] section tells Hop3 how to prepare your application.
[build]
# Use the local builder - Python toolchain is auto-detected from requirements.txt
builder = "local"

# The [run] section specifies the command to start your application.
[run]
start = "gunicorn --workers 2 --bind 0.0.0.0:$PORT app:app"

# The [port] section declares which internal port should be exposed to the web.
[port.web]
container = 5000 # This should match the port gunicorn listens on if PORT isn't set.
public = true

Step 3: Deploy to Hop3¶

With your application code and configuration ready, you can now deploy it.

1. Sign the CLI in (first time on this machine):

   hop3 login root@hop3.example.com
   

   Your SSH access to the server is the credential: no password, and no admin user to create first, since the server makes one if there isn't one. The token is stored in ~/.config/hop3-cli/credentials.toml.

   See Signing In for the web dashboard, several servers, and what to do when you can't get in.

2. Bind this checkout to the server: From inside your hello-hop3 project directory, tell Hop3 which server this checkout deploys to. The login recorded the server as the context default:

   hop3 context use default
   

   It asks before writing, then records the choice in .hop3-local.toml (gitignored). Until a checkout is bound, commands that reach a server are refused inside it, so a deploy never lands on a server you did not pick.

3. Deploy the Application: Still in the project directory, run the deploy command:

   hop3 deploy --app hello-hop3
   

   Inside the project directory, Hop3 reads the app name from hop3.toml, so a bare hop3 deploy works too. The first line of output says where the deploy goes: → default (…), bound in this checkout.

   You will see output from Hop3 as it: - Uploads your application code. - Builds the application environment, then installs dependencies. - Starts the application process. - Configures the router to direct traffic to your app.

Step 4: Verify Your Deployment¶

Once the deployment is complete, Hop3 will provide you with the URL for your application, typically in the format http://<app-id>.<your-hop3-host>.

Open your web browser and navigate to the URL. For our example, it would be something like:

http://hello-hop3.hop3.example.com

You should see the "Hello, Hop3!" message from your Flask application.

Step 5: Managing Your App¶

Hop3 provides commands to manage your running application. The CLI output is formatted for readability.

Check Application Status¶

To see the status of your app and its running processes:

hop3 app status --app hello-hop3

You'll see a nicely formatted table showing:

┏━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Application ┃ Status   ┃ Processes ┃ URL             ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ hello-hop3  │ RUNNING  │ web: 2    │ hello-hop3.hop3 │
│             │          │           │ .example.com    │
└─────────────┴──────────┴───────────┴─────────────────┘

For automation and scripts, use JSON output:

hop3 app status --app hello-hop3 --json

{
  "status": "success",
  "data": {
    "name": "hello-hop3",
    "state": "RUNNING",
    "processes": {"web": 2},
    "url": "hello-hop3.hop3.example.com"
  }
}

View Logs¶

To see your application's recent logs, which is useful for debugging:

hop3 app logs --app hello-hop3

List All Applications¶

See all your deployed applications at a glance:

hop3 app list

Destroy the Application¶

If you want to remove the application and all its associated resources:

hop3 app destroy --app hello-hop3

⚠️ Destructive commands require confirmation. To prevent accidental deletion, you'll be prompted:

WARNING: This will permanently delete the app 'hello-hop3' and all its data.
Type the app name to confirm: hello-hop3

To skip confirmations in scripts, use the -y flag:

hop3 app destroy --app hello-hop3 -y

hop3 deploy --app myapp --quiet
hop3 app status --app myapp --json --quiet

Step 6: Backup and Restore¶

Hop3 includes a backup system to protect your applications. Always take a backup before making significant changes.

# Create a backup (includes code, data, env vars, and attached services)
hop3 backup create --app hello-hop3

# List your backups
hop3 backup list --app hello-hop3

# Restore if needed
hop3 backup restore <backup-id>
hop3 app restart --app hello-hop3

hop3 backup create --app hello-hop3  # Create backup
hop3 deploy --app hello-hop3         # Deploy new version
# If something goes wrong:
hop3 backup restore <backup-id>
hop3 app restart --app hello-hop3

For complete backup documentation, including what's backed up, retention policies, and troubleshooting, see the Backup and Restore Guide.

Step 7: Working with Environment Variables¶

Applications often need configuration through environment variables. Hop3 provides straightforward commands for this.

Setting Environment Variables¶

Set a single environment variable:

hop3 env set --app hello-hop3 LOG_LEVEL=info

Set several variables in one command:

hop3 env set --app hello-hop3 LOG_LEVEL=info MAX_WORKERS=4 SECRET_KEY=your-secret

Viewing Environment Variables¶

List all environment variables for your app:

hop3 env show --app hello-hop3

You'll see a formatted table:

┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ Variable    ┃ Value             ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ PORT        │ 5000              │
│ DEBUG       │ true              │
│ LOG_LEVEL   │ info              │
│ MAX_WORKERS │ 4                 │
└─────────────┴───────────────────┘

Get a specific variable's value:

hop3 env get --app hello-hop3 DEBUG

For scripts, use JSON output:

hop3 env show --app hello-hop3 --json

{
  "status": "success",
  "data": {
    "PORT": "5000",
    "DEBUG": "true",
    "LOG_LEVEL": "info",
    "MAX_WORKERS": "4"
  }
}

Removing Environment Variables¶

Remove a variable:

hop3 env unset --app hello-hop3 DEBUG

hop3 app restart --app hello-hop3

Advanced CLI Features¶

JSON Output for Automation¶

Almost all Hop3 commands support --json output for scripting and automation:

# Get app status in JSON
hop3 app status --app myapp --json | jq '.data.state'

# List all apps and filter by status
hop3 app list --json | jq '.data[] | select(.state == "RUNNING")'

# Create backup and capture backup ID
BACKUP_ID=$(hop3 backup create --app myapp --json | jq -r '.data.backup_id')
echo "Created backup: $BACKUP_ID"

Quiet Mode for Scripts¶

Use --quiet to suppress progress messages and only show essential output:

# Silent deployment (only errors shown)
hop3 deploy --app myapp --quiet

# Combine with JSON for clean machine-readable output
hop3 app list --json --quiet

Skipping Confirmations¶

For automation, skip confirmation prompts with -y:

# Automated cleanup script
hop3 app destroy --app old-app -y
hop3 backup destroy old-backup-id -y

⚠️ The -y flag bypasses safety confirmations. Use it with caution.

Verbose Output for Debugging¶

Get detailed output with -v or --verbose:

hop3 deploy --app myapp -v
hop3 app status --app myapp --verbose

Congratulations!¶

You have successfully deployed and managed your first application on Hop3. You can now use this workflow to deploy your own, more complex applications.

Next Steps¶

• CLI Reference - Complete reference for all Hop3 commands
• Backup and Restore Guide - Comprehensive backup documentation
• hop3.toml Reference - Complete configuration file reference
• Migration Guide - Migrate from Heroku, Fly.io, or other platforms

For help at any time, run:

hop3 help
hop3 <command> --help