​
Installation

docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:latest
Bytebase is now accessible at http://localhost:8080.

​
Production Setup

For production deployments:
  1. Review System Requirements to ensure adequate resources.
  2. Configure External PostgreSQL for production deployments.
  3. Configure HTTPS and WebSocket in your gateway (e.g., Nginx) for secure connections.
  4. See the complete Production Setup Guide for additional recommendations.

​
Troubleshooting

​
Docker Compatibility

Docker version must be at least 20.10.24. We recommend using the latest Docker version. If you cannot upgrade Docker, pass --security-opt seccomp=unconfined to docker run as a best effort to avoid the pthread_create failed error. If you encounter a “manifest not found” error, this may be due to:
  • Architecture mismatch: The docker image only supports linux/amd64 and linux/arm64 architectures. If it doesn’t match your OS architecture, you may supply --platform linux/amd64 as a best effort.
  • Outdated Docker version: Your Docker version is too old and doesn’t support manifest lists.

​
Air-gapped Environment

If you need to transfer images to a completely air-gapped environment: 
# Save the image to a tar file
docker save bytebase/bytebase:latest > bytebase-latest.tar

# Transfer the tar file to your target environment
# Then load it on the target system
docker load < bytebase-latest.tar

# Tag and push as described above
docker tag bytebase/bytebase:latest your-registry.acme.com/library/bytebase:latest
docker push your-registry.acme.com/library/bytebase:latest

​
Port Conflicts

If you see bind: address already in use error, it means the port 8080 is already in use on your host. You need to either stop the existing process using the port or configure Bytebase to use a different port via --publish <<YOUR_PORT>>:8080.

​
Connect to Database on Same Host

  • If you run Bytebase inside Docker on Linux, then you need to supply the additional --network host flags in docker run command. This allows Bytebase to connect to database instance running on the same host with localhost.
  • If you run Bytebase inside Docker Desktop on Mac , then you need to use host.docker.internal to connect to database instance running on the same host.

​
Colima Support

Due to the vm mechanism of Colima, try to use the --mount option when starting colima as shown below: 
mkdir ~/volumes
colima start --mount ~/volumes:w
docker run --init \
  --name bytebase \
  --restart always \
  --publish 80:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase bytebase/bytebase:latest \
  --data /var/opt/bytebase \
  --external-url http://bytebase.example.com \
  --port 8080

​
Advanced Options

For more control over the server configuration, see Server Startup Options.

​
China Access

If accessing from China, use the mirror image: 
docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  registry.cn-shanghai.aliyuncs.com/bytebase/bytebase:latest