home / skills / astronomer / agents / managing-astro-local-env

managing-astro-local-env skill

safe

This skill helps you manage your local Airflow environment with the Astro CLI, enabling start, stop, logs, and troubleshooting commands.

npx playbooks add skill astronomer/agents --skill managing-astro-local-env

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: managing-astro-local-env
description: Manage local Airflow environment with Astro CLI. Use when the user wants to start, stop, or restart Airflow, view logs, troubleshoot containers, or fix environment issues. For project setup, see setting-up-astro-project.
---

# Astro Local Environment

This skill helps you manage your local Airflow environment using the Astro CLI.

> **To set up a new project**, see the **setting-up-astro-project** skill.
> **When Airflow is running**, use MCP tools from **authoring-dags** and **testing-dags** skills.

---

## Start / Stop / Restart

```bash
# 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
```

**Default credentials:** admin / admin

**Restart after modifying:** `requirements.txt`, `packages.txt`, `Dockerfile`

---

## Check Status

```bash
astro dev ps
```

---

## View Logs

```bash
# All logs
astro dev logs

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

# Follow in real-time
astro dev logs -f
```

---

## Access Container Shell

```bash
# Bash into scheduler container
astro dev bash

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

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Port 8080 in use | Stop other containers or edit `.astro/config.yaml` |
| Container won't start | `astro dev kill` then `astro dev start` |
| Package install failed | Check `requirements.txt` syntax |
| DAG not appearing | Run `astro dev parse` to check for import errors |
| Out of disk space | `docker system prune` |

### Reset Environment

When things are broken:

```bash
astro dev kill
astro dev start
```

---

## Upgrade Airflow

### Test compatibility first

```bash
astro dev upgrade-test
```

### Change version

1. Edit `Dockerfile`:
   ```dockerfile
   FROM quay.io/astronomer/astro-runtime:13.0.0
   ```

2. Restart:
   ```bash
   astro dev kill && astro dev start
   ```

---

## Related Skills

- **setting-up-astro-project**: Initialize projects and configure dependencies
- **authoring-dags**: Write DAGs (uses MCP tools, requires running Airflow)
- **testing-dags**: Test DAGs (uses MCP tools, requires running Airflow)

Overview

This skill manages a local Airflow environment using the Astro CLI. It provides commands and guidance to start, stop, restart, inspect logs, troubleshoot containers, and reset or upgrade the runtime. Use it to keep a reproducible local Airflow instance for development and testing. It complements project setup and DAG authoring/testing skills.

How this skill works

The skill maps common Astro CLI commands to practical maintenance tasks: starting and stopping containers, checking container status, viewing and following logs, and opening shells inside containers. It advises on restart triggers (changes to dependencies or Dockerfile), offers troubleshooting steps for common failures, and provides a safe reset sequence. It also outlines how to test and change Airflow versions via the runtime Dockerfile.

When to use it

Start a local Airflow instance for development or manual testing
Stop or restart services after dependency or Dockerfile changes
Inspect logs or follow real-time output to debug scheduler/webserver issues
Run Airflow CLI commands or open a shell inside containers
Reset the environment when containers are unhealthy or corrupted

Best practices

Restart Airflow after modifying requirements.txt, packages.txt, or the Dockerfile
Use astro dev ps to confirm component status before debugging
Follow logs (astro dev logs -f) while reproducing issues to capture errors
Use astro dev kill then astro dev start for a clean reset when containers fail to recover
Test Airflow version upgrades with astro dev upgrade-test before changing the Dockerfile

Example use cases

Start local Airflow and confirm webserver is available at http://localhost:8080
Follow scheduler logs to diagnose missed DAG runs: astro dev logs --scheduler -f
Open a shell in the scheduler container to run airflow CLI commands: astro dev bash; astro dev run airflow dags list
Reset a broken environment: astro dev kill && astro dev start to remove and recreate containers
Upgrade Airflow runtime by editing the FROM line in Dockerfile and restarting the environment

FAQ

What are the default Airflow credentials?

Default credentials are admin / admin.

What should I do if the webserver port is already in use?

Stop the process using port 8080 or change the port in .astro/config.yaml and restart the environment.

How do I recover when a container won't start?

Run astro dev kill to remove containers and volumes if needed, then astro dev start to recreate the environment.