Deployment Environments

Graft allows you to manage multiple isolated deployment environments for a single project. This is ideal for testing features in a dev or staging environment before pushing to production.

Note

By default, the environment is prod or production. If an environment is not explicitly mentioned in a command, Graft defaults to this production environment.

Creating a New Environment

To create a new deployment environment, use the env command with the --new flag:

graft env --new <name>
# or
graft -p env --new <name>

Interactive Setup: When you create a new environment, Graft will guide you through an interactive setup process:

1. Host Configuration: Specify the remote server IP and SSH details for this environment.
2. Host Setup: Graft performs necessary server-side preparations (Docker installation, folder structure).
3. Webhook Integration: Prepare a unique graft-hook for this environment.
4. Git Branch Connection: Connect the environment to a specific Git branch (e.g., dev branch for the dev environment).

---

Listing Environments

To see all configured environments for the current project, run:

graft env ls
# or from anywhere
graft -p my-project env ls

Example output:

📋 Environments for project 'myapp':
Environment     Registry        Domain                         Mode
-------------------------------------------------------------------------------------
prod            prod-us         myapp.com                      git-images
staging         staging-eu      staging.myapp.com              git-images

• Environment — the environment identifier used in graft env <name> <command>.
• Registry — the registry entry (server) this environment is bound to.
• Domain — the primary domain configured for this environment.
• Mode — the deployment mode in use (e.g. git-images, direct-serverbuild).

---

Running Commands in an Environment

Once an environment is set up, you can run any Graft command against it by prefixing the command with env <name>.

graft env <name> <command>
# or
graft -p env <name> <command>

Examples

Synchronize a specific environment:

graft env dev sync

View logs for the webhook in an environment:

graft env staging hook logs graft-hook

Run any graft command:

graft env dev ls
graft env staging ps

[!TIP] Graft also supports passing through commands to the remote server, including docker compose commands via graft env <name> compose ....

---

Environment Separation

Each environment is completely isolated:

• Different remote servers (optional).
• Different webhooks.
• Different Git branches.
• Different environment variables (see Environment Variables).