haloy-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Haloy Configuration

Haloy 配置

Create

haloy.yaml

configuration files for deploying applications with haloy.

If no Dockerfile exists and the user needs one, inform them:

"No Dockerfile found in this project. Haloy deploys Docker containers, so you'll need a Dockerfile first. Would you like me to create one using the
dockerize
skill?"

为使用haloy部署应用创建

haloy.yaml

配置文件。

如果项目中不存在Dockerfile且用户需要，告知用户：

"当前项目中未找到Dockerfile。Haloy部署的是Docker容器，因此你需要先创建一个Dockerfile。是否需要我使用
dockerize
技能为你创建？"

How It Works

工作流程

Check for Dockerfile - Verify the project can be containerized
Check for configured haloy servers - Look for existing server configurations
Detect the project type by examining:
- ```
package.json
```
  with framework dependencies (Next.js, TanStack Start, Express, etc.)
- ```
pyproject.toml
```
  ,
```
requirements.txt
```
  ,
```
Pipfile
```
  (Python/Django/FastAPI)
- ```
go.mod
```
  (Go)
- ```
Cargo.toml
```
  (Rust)
- ```
Gemfile
```
  (Ruby/Rails)
- ```
composer.json
```
  (PHP/Laravel)
Detect database dependencies (Prisma, Drizzle, pg, SQLAlchemy, etc.)
Infer defaults for app name, port, and health check path
Ask the user for server (from configured list or manual entry) and domain
If database detected, ask if they want self-hosted or external
Generate haloy.yaml with appropriate configuration
Provide next steps for validation and deployment

检查Dockerfile - 验证项目是否可容器化
检查已配置的haloy服务器 - 查找现有的服务器配置
检测项目类型，通过检查以下文件：
- 包含框架依赖的
```
package.json
```
  （Next.js、TanStack Start、Express等）
- ```
pyproject.toml
```
  、
```
requirements.txt
```
  、
```
Pipfile
```
  （Python/Django/FastAPI）
- ```
go.mod
```
  （Go语言）
- ```
Cargo.toml
```
  （Rust语言）
- ```
Gemfile
```
  （Ruby/Rails）
- ```
composer.json
```
  （PHP/Laravel）
检测数据库依赖（Prisma、Drizzle、pg、SQLAlchemy等）
推断默认值，包括应用名称、端口和健康检查路径
询问用户服务器信息（从已配置列表选择或手动输入）和域名
如果检测到数据库，询问用户是使用自托管数据库还是外部数据库
生成haloy.yaml，配置相应的参数
提供后续步骤，包括验证和部署

Project Detection

项目检测

Detect the framework to determine the default port:

Framework	Indicator	Default Port
Next.js	`next` in package.json dependencies	3000
TanStack Start	`@tanstack/react-start` in package.json	3000
Express/Node.js	`express` in package.json or generic Node	3000
Vite	`vite` in package.json	5173 (dev) / 3000 (prod)
Django	`django` in requirements.txt or pyproject.toml	8000
FastAPI	`fastapi` in requirements.txt or pyproject.toml	8000
Flask	`flask` in requirements.txt or pyproject.toml	5000
Go	`go.mod` present	8080
Rust	`Cargo.toml` present	8080
Ruby/Rails	`rails` in Gemfile	3000
PHP/Laravel	`laravel` in composer.json	8000
Default	Unknown framework	8080

Also check the Dockerfile for

EXPOSE

directives which override framework defaults.

通过检测框架来确定默认端口：

框架	识别标识	默认端口
Next.js	`package.json` 依赖中包含 `next`	3000
TanStack Start	`package.json` 依赖中包含 `@tanstack/react-start`	3000
Express/Node.js	`package.json` 依赖中包含 `express` 或为通用Node项目	3000
Vite	`package.json` 依赖中包含 `vite`	5173（开发环境）/ 3000（生产环境）
Django	`requirements.txt` 或 `pyproject.toml` 中包含 `django`	8000
FastAPI	`requirements.txt` 或 `pyproject.toml` 中包含 `fastapi`	8000
Flask	`requirements.txt` 或 `pyproject.toml` 中包含 `flask`	5000
Go	存在 `go.mod` 文件	8080
Rust	存在 `Cargo.toml` 文件	8080
Ruby/Rails	`Gemfile` 中包含 `rails`	3000
PHP/Laravel	`composer.json` 中包含 `laravel`	8000
默认	未知框架	8080

同时检查Dockerfile中的

EXPOSE

指令，该指令会覆盖框架默认端口。

Database Detection

数据库检测

Scan for database dependencies to determine if the project uses a database:

Indicator	Database Type
`@prisma/client` , `prisma` in package.json	Check schema for provider
`drizzle-orm` in package.json	Check config for driver
`pg` , `postgres` in package.json	PostgreSQL
`mysql2` in package.json	MySQL
`better-sqlite3` , `sqlite3` in package.json	SQLite (no service needed)
`sequelize` , `typeorm` in package.json	Check config for dialect
`psycopg2` , `asyncpg` in requirements.txt	PostgreSQL
`sqlalchemy` in requirements.txt	Check config for driver
`django` in requirements.txt	Check settings for database
`prisma/schema.prisma` file exists	Check `provider` in datasource block

Prisma schema example - look for the provider:

prisma

datasource db {
  provider = "postgresql"  // or "mysql", "sqlite"
  url      = env("DATABASE_URL")
}

扫描数据库依赖以确定项目是否使用数据库：

识别标识	数据库类型
`package.json` 中包含 `@prisma/client` 、 `prisma`	检查schema中的provider
`package.json` 中包含 `drizzle-orm`	检查配置中的driver
`package.json` 中包含 `pg` 、 `postgres`	PostgreSQL
`package.json` 中包含 `mysql2`	MySQL
`package.json` 中包含 `better-sqlite3` 、 `sqlite3`	SQLite（无需服务）
`package.json` 中包含 `sequelize` 、 `typeorm`	检查配置中的dialect
`requirements.txt` 中包含 `psycopg2` 、 `asyncpg`	PostgreSQL
`requirements.txt` 中包含 `sqlalchemy`	检查配置中的driver
`requirements.txt` 中包含 `django`	检查settings中的数据库配置
存在 `prisma/schema.prisma` 文件	检查datasource块中的 `provider`

Prisma schema示例 - 查找provider：

prisma

datasource db {
  provider = "postgresql"  // 或 "mysql", "sqlite"
  url      = env("DATABASE_URL")
}

Decision Flow

决策流程

Use defaults unless a critical value is missing. Only ask the user when necessary.

除非缺少关键值，否则使用默认值。仅在必要时询问用户。

App Name

应用名称

First choice:
```
name
```
field in
```
package.json
```
Second choice: Project folder name
Ask if: Name contains invalid characters or is generic (e.g., "app", "project")

首选：
```
package.json
```
中的
```
name
```
字段
次选：项目文件夹名称
询问情况：名称包含无效字符或过于通用（例如"app"、"project"）

Server URL

服务器URL

Check for configured servers in

~/.config/haloy/client.yaml

yaml

undefined

检查

~/.config/haloy/client.yaml

中的已配置服务器：

yaml

undefined

Example client.yaml structure

示例client.yaml结构

servers: example.haloy.dev: token_env: HALOY_API_TOKEN_example_HALOY_DEV prod.mycompany.com: token_env: HALOY_API_TOKEN_PROD


**Decision flow:**

1. **If servers found**: Present them as options and let the user choose. The server keys (e.g., `example.haloy.dev`) are the values to use in the config.
   > "I found these configured haloy servers. Which one would you like to deploy to?"
   > - example.haloy.dev
   > - prod.mycompany.com
   > - Enter a different server

2. **If no servers found**: Check if haloy CLI is installed by running `which haloy` or `haloy --version`
   - **If haloy is installed**: Ask for the server URL manually
     > "What is your haloy server URL? (e.g., haloy.yourserver.com)"
   - **If haloy is not installed**: Inform the user they need to install and configure the CLI first
     > "No haloy servers configured. To deploy with haloy, you'll need to install the CLI and add a server. See: https://haloy.dev/docs/client-installation"

servers: example.haloy.dev: token_env: HALOY_API_TOKEN_example_HALOY_DEV prod.mycompany.com: token_env: HALOY_API_TOKEN_PROD


**决策流程**：

1. **如果找到服务器**：将其作为选项展示，让用户选择。服务器键（例如`example.haloy.dev`）是配置中要使用的值。
   > "我找到了这些已配置的haloy服务器。你想部署到哪一个？"
   > - example.haloy.dev
   > - prod.mycompany.com
   > - 输入其他服务器

2. **如果未找到服务器**：通过运行`which haloy`或`haloy --version`检查是否安装了haloy CLI
   - **如果已安装haloy**：手动询问服务器URL
     > "你的haloy服务器URL是什么？（例如haloy.yourserver.com）"
   - **如果未安装haloy**：告知用户需要先安装并配置CLI
     > "未配置haloy服务器。要使用haloy部署，你需要安装CLI并添加服务器。查看：https://haloy.dev/docs/client-installation"

Domain

域名

Always ask - Required for web applications
Example prompt: "What domain should this app be accessible at? (e.g., myapp.example.com)"
If user says "none" or "skip", omit the domains section

必须询问 - Web应用必填
示例提示："这个应用应该通过哪个域名访问？（例如myapp.example.com）"
如果用户说"none"或"skip"，则省略domains部分

Domain Aliases

域名别名

Ask after domain: Once the user provides a domain, ask if they want to add any aliases
Example prompt: "Would you like to add any domain aliases? (e.g., www.myapp.example.com)"
Common alias:
```
www.
```
prefix of the main domain
If user says "none" or "skip", omit the aliases

询问域名后：用户提供域名后，询问是否要添加别名
示例提示："你想添加域名别名吗？（例如www.myapp.example.com）"
常见别名：主域名的
```
www.
```
前缀
如果用户说"none"或"skip"，则省略aliases部分

DNS Reminder

DNS提醒

After gathering domain information, remind the user to configure DNS:

"Remember to configure DNS with your domain provider. Point your domain(s) to your haloy server's IP address using an A record, or use a CNAME record if your server has a domain name."

收集域名信息后，提醒用户配置DNS：

"请记得在域名提供商处配置DNS。使用A记录将域名指向你的haloy服务器IP地址，或者如果服务器有域名，使用CNAME记录。"

Port

端口

Use framework default from the table above
Check Dockerfile for
```
EXPOSE
```
directive which takes precedence
Ask only if: Multiple ports exposed or no clear default

使用框架默认值：来自上方的表格
检查Dockerfile：
```
EXPOSE
```
指令优先级更高
询问情况：存在多个暴露端口或无明确默认值

Health Check Path

健康检查路径

Search for existing endpoints:
```
/health
```
,
```
/healthz
```
,
```
/api/health
```
,
```
/_health
```
If found: Use the existing health endpoint
If not found: Use
```
/
```
(root path)
Do NOT ask - haloy will use
```
/
```
by default which works for most apps

搜索现有端点：
```
/health
```
、
```
/healthz
```
、
```
/api/health
```
、
```
/_health
```
如果找到：使用现有健康端点
如果未找到：使用
```
/
```
（根路径）
无需询问 - haloy默认使用
```
/
```
，适用于大多数应用

Database

数据库

If database dependencies are detected (see Database Detection section):

Ask the user:
"I detected database dependencies ([detected type]). Would you like to add a self-hosted database service, or will you use an external provider (Supabase, Neon, RDS, etc.)?"
- Add self-hosted database
- Use external provider (I'll configure DATABASE_URL myself)
If self-hosted:
- Generate multi-target config with database service + app target
- Use the
```
database
```
  preset for the database target
- Add appropriate environment variables with placeholder values
- Add volume for data persistence
- Database defaults by type:
Database Image Port Volume Path
PostgreSQL
postgres:17
5432
/var/lib/postgresql/data
MySQL
mysql:8
3306
/var/lib/mysql
If external provider:
- Generate single-target config as usual
- Remind user: "Remember to set the
```
DATABASE_URL
```
  environment variable for your external database."

Database	Image	Port	Volume Path
PostgreSQL	`postgres:17`	5432	`/var/lib/postgresql/data`
MySQL	`mysql:8`	3306	`/var/lib/mysql`

如果检测到数据库依赖（请参阅数据库检测部分）：

询问用户：
"我检测到数据库依赖（[检测到的类型]）。你想添加自托管数据库服务，还是使用外部提供商（Supabase、Neon、RDS等）？"
- 添加自托管数据库
- 使用外部提供商（我会自行配置DATABASE_URL）
如果选择自托管：
- 生成包含数据库服务和应用目标的多目标配置
- 为数据库目标使用
```
database
```
  预设
- 添加带有占位符值的相应环境变量
- 添加用于数据持久化的卷
- 按类型设置数据库默认值：
数据库镜像端口卷路径
PostgreSQL
postgres:17
5432
/var/lib/postgresql/data
MySQL
mysql:8
3306
/var/lib/mysql
如果选择外部提供商：
- 按常规生成单目标配置
- 提醒用户："请记得为外部数据库设置
```
DATABASE_URL
```
  环境变量。"

数据库	镜像	端口	卷路径
PostgreSQL	`postgres:17`	5432	`/var/lib/postgresql/data`
MySQL	`mysql:8`	3306	`/var/lib/mysql`

Configuration Reference

配置参考

Haloy supports two modes:

Single Deployment: No
```
targets
```
defined, root configuration is the deployment target
Multi-Target:
```
targets
```
defined, root acts as base/default configuration

Haloy支持两种模式：

单部署：未定义
```
targets
```
，根配置即为部署目标
多目标：定义
```
targets
```
，根配置作为基础/默认配置

Minimal Configuration (Single Deployment)

最小配置（单部署）

yaml

name: "my-app"
server: "haloy.yourserver.com"

yaml

name: "my-app"
server: "haloy.yourserver.com"

With Domain and Port

包含域名和端口的配置

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
    aliases:
      - "www.my-app.example.com"
port: "3000"
health_check_path: "/health"

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
    aliases:
      - "www.my-app.example.com"
port: "3000"
health_check_path: "/health"

With Environment Variables

包含环境变量的配置

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
port: "3000"
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "DATABASE_URL"
    value: "postgres://user:pass@db:5432/myapp"

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
port: "3000"
env:
  - name: "NODE_ENV"
    value: "production"
  - name: "DATABASE_URL"
    value: "postgres://user:pass@db:5432/myapp"

With Volumes (for persistent data)

包含卷的配置（用于持久化数据）

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
volumes:
  - "app-data:/app/data"

yaml

name: "my-app"
server: "haloy.yourserver.com"
domains:
  - domain: "my-app.example.com"
volumes:
  - "app-data:/app/data"

With Self-Hosted Database (Multi-Target)

包含自托管数据库的配置（多目标）

yaml

server: "haloy.yourserver.com"
env:
  - name: POSTGRES_USER
    value: "postgres"
  - name: POSTGRES_PASSWORD
    value: "change-me-in-production"
  - name: POSTGRES_DB
    value: "my_app"

targets:
  postgres:
    preset: database
    image:
      repository: postgres:17
    port: 5432
    volumes:
      - postgres-data:/var/lib/postgresql/data

  my-app:
    domains:
      - domain: "my-app.example.com"
    port: 3000
    env:
      - name: DATABASE_URL
        value: "postgres://postgres:change-me-in-production@postgres:5432/my_app"
      - name: NODE_ENV
        value: "production"

yaml

server: "haloy.yourserver.com"
env:
  - name: POSTGRES_USER
    value: "postgres"
  - name: POSTGRES_PASSWORD
    value: "change-me-in-production"
  - name: POSTGRES_DB
    value: "my_app"

targets:
  postgres:
    preset: database
    image:
      repository: postgres:17
    port: 5432
    volumes:
      - postgres-data:/var/lib/postgresql/data

  my-app:
    domains:
      - domain: "my-app.example.com"
    port: 3000
    env:
      - name: DATABASE_URL
        value: "postgres://postgres:change-me-in-production@postgres:5432/my_app"
      - name: NODE_ENV
        value: "production"

Multi-Target Example

多目标示例

yaml

undefined

yaml

undefined

Base settings inherited by all targets

所有目标继承的基础设置

image: repository: "my-app" tag: "latest" port: "3000"

targets: production: server: "prod.haloy.com" domains: - domain: "my-app.com" replicas: 2 staging: server: "staging.haloy.com" domains: - domain: "staging.my-app.com" replicas: 1

undefined

image: repository: "my-app" tag: "latest" port: "3000"

targets: production: server: "prod.haloy.com" domains: - domain: "my-app.com" replicas: 2 staging: server: "staging.haloy.com" domains: - domain: "staging.my-app.com" replicas: 1

undefined

Full Reference

完整参考

For all configuration options, see: https://haloy.dev/docs/configuration-reference

Key options:

```
name
```
- Application name (required for single deployment)
```
server
```
- Haloy server URL (required)
```
image
```
- Docker image configuration (repository, tag)
```
domains
```
- Array of domain objects with
```
domain
```
and optional
```
aliases
```
```
port
```
- Container port (default: "8080")
```
health_check_path
```
- Health check endpoint (default: "/")
```
env
```
- Environment variables as name/value pairs
```
volumes
```
- Volume mounts for persistent data
```
replicas
```
- Number of container instances (default: 1)
```
deployment_strategy
```
- "rolling" (default) or "replace"
```
targets
```
- Define multiple deployment targets (multi-target mode)
```
preset
```
- Apply preset configuration ("database" or "service")

所有配置选项请查看：https://haloy.dev/docs/configuration-reference

关键选项：

```
name
```
- 应用名称（单部署必填）
```
server
```
- Haloy服务器URL（必填）
```
image
```
- Docker镜像配置（repository、tag）
```
domains
```
- 包含
```
domain
```
和可选
```
aliases
```
的域名对象数组
```
port
```
- 容器端口（默认："8080"）
```
health_check_path
```
- 健康检查端点（默认："/"）
```
env
```
- 键值对形式的环境变量
```
volumes
```
- 用于持久化数据的卷挂载
```
replicas
```
- 容器实例数量（默认：1）
```
deployment_strategy
```
- "rolling"（默认）或"replace"
```
targets
```
- 定义多个部署目标（多目标模式）
```
preset
```
- 应用预设配置（"database"或"service"）

Output Format

输出格式

After gathering information, create the

haloy.yaml

file and provide:

The haloy.yaml file - Written to the project root
Update .dockerignore - Add
```
haloy.yaml
```
to
```
.dockerignore
```
if not already present. This improves Docker layer caching since changes to
```
haloy.yaml
```
won't invalidate the build cache.
Validation command:
bash
```
haloy validate-config
```
Deployment command:
bash
```
haloy deploy
```

If haloy CLI is not installed, show installation options:

bash

# Shell script
curl -fsSL https://sh.haloy.dev/install-haloy.sh | sh

# Homebrew
brew install haloydev/tap/haloy

# npm/pnpm/bun
npm install -g haloy
pnpm add -g haloy
bun add -g haloy

收集信息后，创建

haloy.yaml

文件并提供：

haloy.yaml文件 - 写入项目根目录
更新.dockerignore - 如果
```
haloy.yaml
```
尚未存在，将其添加到
```
.dockerignore
```
中。这可以改善Docker层缓存，因为
```
haloy.yaml
```
的更改不会使构建缓存失效。
验证命令：
bash
```
haloy validate-config
```
部署命令：
bash
```
haloy deploy
```

如果未安装haloy CLI，显示安装选项：

bash

# Shell脚本
curl -fsSL https://sh.haloy.dev/install-haloy.sh | sh

# Homebrew
brew install haloydev/tap/haloy

# npm/pnpm/bun
npm install -g haloy
pnpm add -g haloy
bun add -g haloy

Example Interactions

示例交互

See

references/examples.md

for detailed interaction examples covering:

Deploying with configured servers
Database detection and self-hosted database setup
Handling missing server configuration

详细的交互示例请查看

references/examples.md

，包括：

使用已配置服务器部署
数据库检测和自托管数据库设置
处理缺失的服务器配置