managing-astro-local-env

Astro のローカル環境

このスキルでは、Astro CLI を使用してローカルの Airflow 環境を管理します。

2 つのモードがあります。Docker（デフォルト。コンテナを使用）と Standalone（Docker 不要。ローカルの venv を使用 — Airflow 3 と uv が必要）です。

新しいプロジェクトをセットアップするには、 setting-up-astro-project スキルを参照してください。 Airflow の実行中は、 authoring-dags と testing-dags スキルの MCP ツールを使用してください。

---

起動／停止／再起動（Docker）

# Start local Airflow (webserver at http://localhost:8080)
astro dev start

# Stop containers (preserves data)
astro dev stop

# Kill and remove volumes (clean slate)
astro dev kill

# Restart all containers
astro dev restart

# Restart specific component
astro dev restart --scheduler
astro dev restart --webserver

デフォルトの認証情報： admin / admin

次のファイルを変更した後は再起動してください： requirements.txt、packages.txt、Dockerfile

Standalone モードを使用していますか？ 次のセクションを参照してください。

---

Standalone モード

Docker を使用しないローカル開発です。uv で管理される .venv/ 内で、Airflow をマシン上で直接実行します。

要件： Airflow 3（ランタイム 3.x）、PATH 上に uv があること。Windows はサポートされていません。

通常の astro dev init では、すでにランタイム 3.x のイメージが固定されるため、バージョンフラグは不要です。プロジェクトの初期化については setting-up-astro-project を参照してください。

起動

# One-time: set standalone as default mode
astro config set dev.mode standalone

# Or use the flag per invocation
astro dev start --standalone

フラグ	説明
--foreground / -f	出力をフォアグラウンドにストリーミングする
--port / -p	Web サーバーのポートを上書きする（デフォルト：8080）
--no-proxy	リバースプロキシを無効にする

停止／強制終了／再起動

# Stop (preserves .venv)
astro dev stop

# Kill (removes .venv and .astro/standalone/ — clean slate)
astro dev kill

# Restart (preserves .venv for fast restart, use -k to kill first)
astro dev restart

設定ではなく起動時に --standalone を使用した場合は、その後のコマンド（stop、kill、restart、bash、run、logs など）でも毎回 --standalone を指定してください。

状態の保存場所： venv は .venv/、データベースとログは .astro/standalone/、DAG は dags/ にあります。

---

リバースプロキシ

ポートの競合なしで、複数の Airflow プロジェクトをローカルで実行できます。Docker モードと Standalone モードのどちらでも動作します。

各プロジェクトには <project-name>.localhost:6563 のようなホスト名が割り当てられます。http://localhost:6563 にアクセスすると、アクティブなプロジェクトがすべて表示されます。

# Check proxy status and active routes
astro dev proxy status

# Force-stop proxy (auto-restarts on next astro dev start)
astro dev proxy stop

設定	コマンド
プロキシのポートを変更	astro config set proxy.port <port>
起動ごとに無効化	astro dev start --no-proxy

デフォルトのプロキシポート：6563

---

ステータスの確認

astro dev ps

---

ログの表示

# All logs
astro dev logs

# Specific component
astro dev logs --scheduler
astro dev logs --webserver

# Follow in real-time
astro dev logs -f

Standalone： astro dev logs は同様に動作しますが、統合されたログが表示されます（コンポーネントごとのフィルタリングはありません）。

---

Airflow CLI コマンドの実行

# Open a shell with Airflow environment
astro dev bash

# Run Airflow CLI commands
astro dev run airflow info
astro dev run airflow dags list

Standalone： 同じコマンドを使用できます。bash は venv が有効化されたシェルを開き、run は venv 内で実行します。

---

Airflow API のクエリ

astro api airflow を使用して、実行中のローカル Airflow インスタンスにクエリを実行します。URL パスよりも操作 ID を優先してください。

デフォルト： localhost:8080、admin/admin（自動検出）。--api-url、--username、--password で上書きできます。

検出

# List all endpoints
astro api airflow ls

# Filter by keyword
astro api airflow ls dags
astro api airflow ls task

# Show params and schema for an operation
astro api airflow describe get_dag

主なフラグ

フラグ	用途
-p key=value	パスパラメーター
-F key=value	本文／クエリのフィールド（ブール値／数値を自動変換）
-q / --jq	レスポンスに対する jq フィルター
--paginate	すべてのページを取得
-X / --method	HTTP メソッドを上書き
--generate	実行せずに curl コマンドを出力

DAG

# List all DAGs
astro api airflow get_dags

# Filter by pattern (SQL LIKE — use % wildcards)
astro api airflow get_dags -F dag_id_pattern=%etl%

# Get a specific DAG
astro api airflow get_dag -p dag_id=my_dag

# Get full details (schedule, params, etc.)
astro api airflow get_dag_details -p dag_id=my_dag

# Pause / unpause
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=true
astro api airflow patch_dag -p dag_id=my_dag -F is_paused=false

# View DAG source code
astro api airflow get_dag_source -p dag_id=my_dag

# Check import errors
astro api airflow get_import_errors

DAG 実行

# List runs for a DAG
astro api airflow get_dag_runs -p dag_id=my_dag

# Trigger a run
astro api airflow trigger_dag_run -p dag_id=my_dag

# Trigger with config
astro api airflow trigger_dag_run -p dag_id=my_dag -F conf[key]=value

# Get a specific run
astro api airflow get_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# Clear (re-run) a DAG run
astro api airflow clear_dag_run -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -F dry_run=false

タスクインスタンス

# List task instances for a run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=manual__2026-04-07

# Use ~ as wildcard (all DAGs or all runs)
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~

# Get a specific task instance
astro api airflow get_task_instance -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 -p task_id=extract

# Clear/retry failed tasks
astro api airflow post_clear_task_instances -p dag_id=my_dag \
  -F dag_run_id=manual__2026-04-07 -F only_failed=true -F dry_run=false

# Get task logs
astro api airflow get_log -p dag_id=my_dag -p dag_run_id=manual__2026-04-07 \
  -p task_id=extract -p try_number=1

設定と接続

astro api airflow get_connections
astro api airflow get_variables
astro api airflow get_config

jq によるフィルタリング

# List only DAG IDs
astro api airflow get_dags -q '.dags[].dag_id'

# Get failed task IDs from a run
astro api airflow get_task_instances -p dag_id=my_dag -p dag_run_id=~ \
  -q '[.task_instances[] | select(.state=="failed") | .task_id]'

---

トラブルシューティング

問題	解決策
ポート 8080 が使用中	他のコンテナを停止するか、.astro/config.yaml を編集してください
コンテナが起動しない	astro dev kill を実行してから astro dev start を実行してください
パッケージのインストールに失敗した	requirements.txt の構文を確認してください
DAG が表示されない	astro dev parse を実行して、インポートエラーがないか確認してください
ディスク容量が不足している	docker system prune
Standalone が起動しない	uv が PATH 上にあり、ランタイムが 3.x であることを確認してください
プロキシポートが競合している	astro config set proxy.port <port>
.venv が破損している	astro dev kill を実行してから astro dev start --standalone を実行してください

環境のリセット

問題が発生した場合：

astro dev kill
astro dev start

---

Airflow のアップグレード

まず互換性をテストする

astro dev upgrade-test

バージョンを変更する

1. Dockerfile を編集します：

   FROM quay.io/astronomer/astro-runtime:13.0.0
   

2. 再起動します：

   astro dev kill && astro dev start
   

---

関連スキル

• setting-up-astro-project：プロジェクトを初期化し、依存関係を設定します
• authoring-dags：DAG を記述します（MCP ツールを使用し、Airflow の実行が必要です）
• testing-dags：DAG をテストします（MCP ツールを使用し、Airflow の実行が必要です）
• deploying-airflow：DAG を本番環境にデプロイします（Astro、Docker Compose、Kubernetes）