Skip to content

docs: Update Flash docs for .flashignore deprecation and built-in ignore patterns #588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
promptless wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Update Flash docs for .flashignore deprecation and built-in ignore patterns #588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion flash/apps/build-app.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ This is the structure of the project template created by `flash init`:
<Tree.File name="gpu_worker.py" />
<Tree.File name="cpu_worker.py" />
<Tree.File name=".env.example" />
<Tree.File name=".flashignore" />
<Tree.File name=".gitignore" />
<Tree.File name="pyproject.toml" />
<Tree.File name="requirements.txt" />
Expand Down
2 changes: 1 addition & 1 deletion flash/apps/deploy-apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Each endpoint maintains its own connection to the state manager, querying for pe
If the build process can't find your endpoint functions:

- Ensure functions are decorated with `@Endpoint(...)`.
- Check that Python files aren't excluded by `.gitignore` or `.flashignore`.
- Check that Python files aren't excluded by `.gitignore` or Flash's [built-in ignore patterns](/flash/cli/build#built-in-ignore-patterns).
- Verify decorator syntax is correct.

### Deployment size limit exceeded
Expand Down
3 changes: 0 additions & 3 deletions flash/apps/initialize-project.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,6 @@ flash init .
<Tree.File name="gpu_worker.py" />
<Tree.File name="cpu_worker.py" />
<Tree.File name=".env.example" />
<Tree.File name=".flashignore" />
<Tree.File name=".gitignore" />
<Tree.File name="pyproject.toml" />
<Tree.File name="requirements.txt" />
Expand All @@ -51,8 +50,6 @@ flash init .

**cpu_worker.py**: An example CPU queue-based worker. Contains `@Endpoint` functions that run on CPU-only instances. Provides `/runsync` route for job submission. Creates one endpoint when deployed.

**.flashignore**: Lists files and directories to exclude from the deployment artifact (similar to `.gitignore`).

Each worker file defines a resource configuration and its associated functions. When you deploy, Flash creates one Serverless endpoint per unique resource configuration.

## Set up the project
Expand Down
15 changes: 15 additions & 0 deletions flash/cli/build.mdx
View file
Open in desktop
Copy link
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Line 82)

Citation: Deprecation note based on the PR description: "Add deprecation warning for users who still have a .flashignore file, guiding them to migrate custom patterns to .gitignore."
View source

Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,21 @@ Comma-separated list of packages to exclude from the build (e.g., `torch,torchvi
5. **Dependency installation**: Installs Python packages for Linux x86_64.
6. **Packaging**: Bundles everything into `.flash/artifact.tar.gz`.

Copy link
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Citation: Built-in ignore patterns extracted from the new always_ignore list in src/runpod_flash/cli/utils/ignore.py. The PR adds these patterns to replace the .flashignore file.
View source

## Built-in ignore patterns

Flash automatically excludes certain files and directories from deployment artifacts. These patterns cover common development files that shouldn't be deployed to production.

| Category | Patterns |
|----------|----------|
| Build artifacts | `.build/`, `.flash/`, `.runpod/`, `*.tar.gz`, `.git/`, `__pycache__/`, `*.pyc`, `*.pyo`, `*.pyd`, `*.egg-info/`, `dist/`, `build/` |
| Virtual environments | `.venv/`, `venv/`, `env/` |
| IDE files | `.vscode/`, `.idea/` |
| Environment files | `.env`, `.env.*` |
Copy link
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Citation: Updated from .env.local to .env.* based on PR #280 which adds the .env.* glob pattern to always_ignore in cli/utils/ignore.py. This ensures all .env variants (.env.local, .env.production, .env.staging, etc.) are excluded from deploy artifacts.
View source

| Tests | `tests/`, `test_*.py`, `*_test.py` |
| Documentation | `docs/`, `*.md` (except `README.md`) |

Flash also respects your `.gitignore` file and excludes any files matching those patterns.

## Build artifacts

After running `flash build`:
Expand Down
1 change: 0 additions & 1 deletion flash/cli/init.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ The command creates the following project structure:
<Tree.File name="gpu_worker.py" />
<Tree.File name="cpu_worker.py" />
<Tree.File name=".env.example" />
<Tree.File name=".flashignore" />
<Tree.File name=".gitignore" />
<Tree.File name="pyproject.toml" />
<Tree.File name="requirements.txt" />
Expand Down
31 changes: 1 addition & 30 deletions flash/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ Tarball exceeds maximum size. File size: 1.6GB, Max: 1.5GB
**Solution:**

1. Check for large files that shouldn't be included (datasets, model weights, logs).
2. Add large files to `.flashignore` to exclude them from the build.
2. Add large files to `.gitignore` to exclude them from the build.
3. Use [network volumes](/flash/configuration/storage) to store large models instead of bundling them.

### Invalid tarball format
Expand All @@ -246,35 +246,6 @@ rm -rf .flash
flash build
```

### SSL certificate verification failed

**Error:**
```
SSL certificate verification failed. This usually means Python cannot find your system's CA certificates.
```

**Cause:** Python cannot locate the system's trusted CA certificates, preventing secure connections during deployment. This commonly occurs on fresh Python installations, especially on macOS.

**Solution:** Try one of these fixes:

1. **Install certifi and set the certificate bundle path:**
```bash
pip install certifi
export REQUESTS_CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")
```

2. **macOS only:** Run the certificate installer that comes with Python. Find it in your Python installation folder (typically `/Applications/Python 3.x/`) and run `Install Certificates.command`.

3. **Add to shell profile for persistence:**
```bash
echo 'export REQUESTS_CA_BUNDLE=$(python -c "import certifi; print(certifi.where())")' >> ~/.bashrc
source ~/.bashrc
```

<Note>
Transient SSL errors (like connection resets) are automatically retried during upload. The certificate verification error requires manual intervention because it indicates a system configuration issue.
</Note>

### Resource provisioning failed

**Error:**
Expand Down
Loading