Container-based example app
Check out the container-based example app for understanding the
basics of running a containerized application on fal.
Dockerfile KeywordsPlease check our Dockerfile best practices for
more information on how to optimize your Dockerfile.
fal Specific Considerations
When deploying your application on fal, you don’t need to worry about enabling Docker Buildx or BuildKit. We take care of it for you. However, there are several fal-specific requirements you must follow:Required Package Versions
fal has specific dependencies that must be installed with exact versions:pydantic==2.10.6
protobuf==4.25.1
boto3==1.35.74
Ensure Curl
1. File Upload Instead of COPY
COPY
and ADD
(from local filesystem) are not supported as of now to copy files into the container
from the host. Instead you can use fal’s fal.toolkit
to upload files and
refer them in the container using links.
NoteIf you are curious about the differences between
COPY
and ADD
, check out
the following link.ADD
to directly download the file from the URL:
2. Container Image Best Practices
When building container images for fal, follow these best practices:Use Fal Base Image
Its recommended to usefalai/base:3.11-12.1.0
as your base image as it comes with the right python version, cuda and more.
Most importantly its small size improves startup times!
Pin All Package Versions
This ensures reproducibility of builds leaving no doors open for issues with newer package versions and incompatibility!Clean Up Package Caches
Cleaning up package caches reduces build time and startup time, making for a faster iteration and coldstart!Use Multi-Stage Builds for Smaller Images
Multi Stage builds are a great way to significantly reduce the image size, saving time building and downloading the container on startup!Docker Templates
To help you get started quickly and avoid common pitfalls, here are production-ready Docker templates for common use cases:Base Python Template
Perfect for applications that only need Python packages from pip or simple apt packages.PyTorch + HuggingFace Template
For deep learning applications using PyTorch and HuggingFace ecosystem.Custom CUDA Template
For some applications, you might require a different cuda runtime, here is an example to get CUDA 12.8:Common Issues & Solutions
fal Dependency Conflicts
Problem:ImportError
or version conflicts with pydantic, protobuf, or boto3
Solution: Always install fal-required packages last:
Python Binary Not Found
Problem:python: command not found
or /usr/bin/env: python: No such file or directory
Solution: Create proper symlinks when using custom base images:
CUDA Related Issues
Example Problem:RuntimeError: No CUDA GPUs are available
Solution: Ensure CUDA environment variables are set:
Container Validation Checklist
Before deploying your container app, ensure:- All package versions are pinned
- fal-required packages (pydantic==2.10.6, protobuf==4.25.1, boto3==1.35.74) are installed LAST
- Curl is installed
- Container builds without errors with fal run
Using Private Docker Registries
To use private docker registries, you need to provide registry credentials like so:Dockerhub
Google Artifact Registry
We recommend using a service account and setting a base64-encoded version of the key as a Fal secret, which you can then use in your code:1
Create a JSON key for a service account. It should be automatically downloaded to your computer.
2
Encode it in base64 with a command like:
3
Set the result as a Fal secret:
4
Use the secret as the password, and
_json_key_base64
as the username for the Artifact Registry in your code:Amazon Elastic Container Registry
Build Secrets
We currently only support secret mounts.Next steps
Optimize your container imageCheck our Optimize Container Images guide for more information on how to optimize your container image.