# Installation
The recommended production target is a dedicated Linux VPS. This guide explains the requirements, setup effects, and completion steps.
AI-assisted installation: This repository includes a
vps-deployment skill (opens new window) for
compatible AI agents. Ask the agent to use this skill to help select a VPS,
perform preflight checks, plan the deployment, guide installation, and verify
the result.
# Requirements
Use the server specifications guide to size a dedicated Linux host for the chains and features you need.
Review Networking for domain, DNS, HTTPS, and public-port requirements.
# Install a Bitcoin Deployment
Follow the current installation commands in the root README (opens new window), replacing the example hostname before running them.
The script must be sourced with . ./btcpay-setup.sh; executing it in a child
shell does not preserve the environment it configures.
# What Setup Changes
On Linux, the setup process:
- Installs Docker when it is not available.
- Installs the repository's pinned Docker Compose version.
- Generates the selected Compose stack and missing secret files.
- Stores container environment values in
$BTCPAY_BASE_DIRECTORY/.env. - Stores the deployment profile in
/etc/profile.d/btcpay-env.sh. - Installs applicable utility symlinks in
/usr/local/bin. - Registers
/etc/systemd/system/btcpayserver.service, or an Upstart service on older systems. - Pulls images and starts the stack.
If /etc/docker/daemon.json does not exist, setup creates a JSON-file logging
configuration limited to three 5 MB files. It does not replace an existing
Docker daemon configuration.
The recommended btcpay-host fragment allows BTCPay Server to invoke a
restricted set of host-management commands and changes host SSH configuration.
Excluding the fragment prevents BTCPay Server from receiving the host key, but
setup still prepares the host-side SSH integration and does not undo prior SSH
changes. Read Configuration for details.
# Complete the Installation
Open https://btcpay.example.com and create the first account. The first
registered account becomes the server administrator, so register it promptly.
Setup can exit successfully even when the ACME companion could not issue a certificate. Follow the Nginx and HTTPS checks and resolve any certificate errors before treating HTTPS as ready.
The site can open before Bitcoin Core and NBXplorer finish synchronizing. Check the synchronization status in BTCPay Server before accepting payments. You can also inspect the node directly:
bitcoin-cli.sh getblockchaininfo
# Change the Deployment
Export the changed values and source setup again:
export BTCPAYGEN_LIGHTNING="clightning"
. ./btcpay-setup.sh -i
Setup persists the effective profile. Do not edit the generated Compose file directly; use configuration variables or custom fragments.