Airbyte Local Installation Steps
Airbyte's recommended local setup is abctl, the command-line
tool that spins up the platform (web app, API and database) with a single
command. This guide covers the install path, the install command, and the
database permission error you are most likely to hit.
1. Create and Set Permissions for the Installation Path
Create the install directory and hand ownership to your user:
sudo mkdir -p /opt/airbyte
sudo chown -R $USER:$(id -gn) /opt/airbyte
The second command is what prevents most permission problems later — the installer and its containers write into this directory.
2. Install Airbyte Locally
Set the installation path and run the Airbyte install command:
ABCTL_LOCAL_PATH=/opt/airbyte abctl local install
Note: Replace /opt/airbyte with your preferred
installation directory if needed.
Troubleshooting: airbyte-db Container in BackOff
If the install stalls or the database pod never becomes ready, you will see a log like this:
Pod: airbyte-db-0.1841d606b9647c61
Reason: BackOff
Message: Back-off restarting failed container airbyte-db-container...
Logs:
chown: /var/lib/postgresql/data/pgdata: Operation not permitted
chmod: /var/lib/postgresql/data/pgdata: Operation not permitted
initdb: error: could not access directory "/var/lib/postgresql/data/pgdata": Permission denied
This means the PostgreSQL container cannot write to its data directory. The usual causes are:
- The
/opt/airbytedirectory (or the volume backingpgdata) is not writable by the container's user — re-runsudo chown -R $USER:$(id -gn) /opt/airbyteand retry. - A previous failed install left a stale volume with wrong ownership —
remove the leftover Airbyte state (e.g.
abctl local reset) and run the install again. - The host filesystem (NFS, some virtualized setups) does not support
chown— install on a local disk instead.