# Guidance on Qtum Deployment

## Guidance on Qtum Deployment

### Overview

This guide covers deploying, running, and making RPC calls to a Qtum node. It assumes basic familiarity with command-line interfaces on Linux, macOS, or Windows. For GUI wallet usage, refer to the [Qtum Wallet Tutorial](https://docs.qtum.site/en/Qtum-Wallet-Tutorial.md).

### Getting Qtum Node

#### 1. Download Prebuilt Binaries

The simplest method is downloading the latest binaries from the [Qtum releases page](https://github.com/qtumproject/qtum/releases). Binaries are available for Linux, Windows, macOS, and Raspberry Pi.

**Current stable version: 29.1** (based on Bitcoin Core 29.1)

**Available platforms:**

* **macOS**: `qtum-{version}-arm64-apple-darwin.dmg` (Apple Silicon) or `qtum-{version}-x86_64-apple-darwin.tar.gz` (Intel)
* **Linux**: `qtum-{version}-x86_64-linux-gnu.tar.gz` (64-bit) or `qtum-{version}-aarch64-linux-gnu.tar.gz` (ARM64)
* **Windows**: `qtum-{version}-win64.zip` (64-bit) or `qtum-{version}-win32.zip` (32-bit)
* **Raspberry Pi**: `qtum-{version}-arm-linux-gnueabihf.tar.gz`

After extraction, `qtumd` and `qtum-cli` binaries will be located in `<install-path>/bin/`.

#### 2. Package Manager Installation (Ubuntu Linux)

**Ubuntu, Debian, and Mint users** can install via apt repository:

```bash
# Add Qtum repository
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BF5B197D
echo "deb https://repo.qtum.info/apt/ubuntu/ $(lsb_release -cs) main" |sudo tee -a /etc/apt/sources.list.d/qtum.list
sudo apt update
sudo apt install qtum
```

**Raspberry Pi users** can also use apt. See the [Raspberry Pi installation guide](https://github.com/qtumproject/qtum/wiki/Installing-Qtum-on-Raspberry-Pi).

After installation, `qtumd` and `qtum-cli` are available system-wide.

#### 3. Build from Source

For the latest development version, clone the repository and build using CMake:

```bash
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum
```

**Build Prerequisites**

Qtum uses CMake for its build system (migrated from Autotools in Bitcoin Core 29.1). Detailed instructions are available in the repository:

* **Linux**: [build-unix.md](https://github.com/qtumproject/qtum/blob/master/doc/build-unix.md)
* **macOS**: [build-osx.md](https://github.com/qtumproject/qtum/blob/master/doc/build-osx.md)
* **Windows**: [build-windows.md](https://github.com/qtumproject/qtum/blob/master/doc/build-windows.md)

**Minimum CMake version required: 3.22**

**macOS Build Example**

```bash
# Install dependencies via Homebrew
brew install cmake boost libevent gmp protobuf qt@6 qrencode

# Clone repository
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

# Configure with CMake
cmake -B build

# Build (use -j N for N parallel jobs)
cmake --build build -j$(sysctl -n hw.physicalcpu)

# Optional: Install binaries
cmake --install build

# Binaries will be in build/src/
```

## How to Run Qtum-Qt.app with a Self-Signed Certificate on macOS

If you have downloaded `Qtum-Qt.app` and want to run it on macOS, you may encounter security restrictions. This guide provides specific instructions for using a self-signed certificate to allow `Qtum-Qt.app` to run.

### Steps

#### 1. Create a Self-Signed Certificate (Skip if you already have a certificate for code signing)

1. Open **Keychain Access** (Applications > Utilities > Keychain Access).
2. In the **Keychain Access** menu, select **Certificate Assistant > Create a Certificate**.
3. Enter a name for your certificate (e.g., "Qtum Certificate").
4. Set **Identity Type** to **Self-Signed Root**.
5. Set **Certificate Type** to **Code Signing**.
6. Click **Create** to generate the certificate.

#### 2. Sign the Qtum-Qt.app Application

1. Open **Terminal**.
2. Use the following `codesign` command to sign `Qtum-Qt.app` with the newly created certificate:

   ```
   codesign --force --deep --sign "Qtum Certificate" /path/to/Qtum-Qt.app
   ```

   Replace "Qtum Certificate" with the name of your certificate, and ensure /path/to/Qtum-Qt.app/ points to the actual location of the app on your system. Remove Qtum from MacOS Quarantine: `sudo xattr -rd com.apple.quarantine Qtum-Qt.app`
3. Open Qtum from the Applications menu

\***Note:** The same procedure can be used to sign `qtumd`, `qtum-cli` and other command line binaries.

#### 4. Docker Image

For users with Docker installed, pull the official Qtum image:

```bash
docker pull qtum/qtum:latest
```

For Docker deployment instructions, see [How to Launch Qtum with Docker](https://github.com/qtumproject/documents/blob/master/zh/Launch-Qtum-with-Docker.md).

### Key Binaries

* **`qtumd`**: Qtum Core daemon (full node)
* **`qtum-cli`**: Command-line interface for RPC calls
* **`qtum-qt`**: GUI wallet application (if built with Qt support)

### Deploy Qtum Node

#### Start the Daemon

```bash
./qtumd -daemon
```

This launches `qtumd` as a background daemon. To enable smart contract event logging, add the `-logevents` flag:

```bash
./qtumd -daemon -logevents
```

#### Additional Options

View all available options:

```bash
./qtumd -help
```

#### Stop the Daemon

```bash
./qtum-cli stop
```

#### Data Directory

The default data directory varies by platform:

* **Linux**: `~/.qtum/`
* **macOS**: `~/Library/Application Support/Qtum/`
* **Windows**: `%APPDATA%\Qtum\`

Use the `-datadir` option to specify a custom location.

#### Initial Blockchain Sync

On first launch, Qtum will sync the entire blockchain history. This may take several hours depending on network speed and hardware. Progress and diagnostics are logged to `~/.qtum/debug.log`.

### Local RPC Calls

With `qtumd` running, use `qtum-cli` to interact with the node:

```bash
./qtum-cli getblockchaininfo
```

Example output:

```json
{
  "chain": "main",
  "blocks": 850123,
  "headers": 850123,
  "bestblockhash": "a1b2c3...",
  "difficulty": 12345678.90,
  "time": 1698765432,
  "verificationprogress": 0.9999
}
```

#### List All RPC Commands

```bash
./qtum-cli help
```

#### Get Help for Specific Commands

```bash
./qtum-cli help getblockchaininfo
```

### JSON-RPC Configuration

#### Remote RPC Setup

To enable remote RPC access, configure RPC credentials using either method:

**Method 1: Configuration File**

Create `~/.qtum/qtum.conf`:

```conf
# RPC credentials (required)
rpcuser=your_username
rpcpassword=your_secure_password

# Allow remote connections (default: localhost only)
# IPv4 example:
#rpcallowip=192.168.1.0/24
# IPv6 example:
#rpcallowip=2001:db8:85a3::/64

# RPC port (default: 3889 for mainnet, 13889 for testnet)
#rpcport=3889

# Enable server mode
server=1
```

For more configuration options, see [qtum.conf example](https://github.com/qtumproject/qtum/blob/master/contrib/debian/examples/qtum.conf).

**Restart the node** after creating or modifying `qtum.conf`.

**Method 2: Command-Line Arguments**

```bash
./qtumd -daemon \
  -rpcuser=your_username \
  -rpcpassword=your_secure_password \
  -rpcallowip=192.168.1.0/24
```

#### JSON-RPC Call Examples

**Using curl**

```bash
curl --user your_username:your_secure_password \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getblockchaininfo","params":[]}' \
  -H 'content-type: text/plain;' \
  http://192.168.1.100:3889/
```

**Using Postman or Similar Tools**

* **URL**: `http://192.168.1.100:3889/`
* **Method**: POST
* **Headers**: `Content-Type: text/plain`
* **Auth**: Basic Auth with RPC username/password
* **Body**:

  ```json
  {  "jsonrpc": "1.0",  "id": "test",  "method": "getblockchaininfo",  "params": []}
  ```

### Nginx Reverse Proxy (Optional)

Nginx can simplify remote RPC access by hiding credentials and providing additional security:

#### Configuration Example

**Setup**: Qtum node at `192.168.1.100`, Nginx proxy at `192.168.1.50`

1. **Update qtum.conf** on the node:

   ```conf
   rpcuser=internal_user
   rpcpassword=internal_password
   rpcallowip=192.168.1.50/32
   ```
2. **Configure Nginx** on the proxy server:

   ```nginx
   server {
       listen 80;
       server_name your-domain.com;

       location / {
           proxy_pass http://192.168.1.100:3889;
           # Base64 encoding of "internal_user:internal_password"
           proxy_set_header Authorization "Basic aW50ZXJuYWxfdXNlcjppbnRlcm5hbF9wYXNzd29yZA==";
       }
   }
   ```
3. **Make RPC calls** through the proxy:

   ```bash
   curl --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' \
     -H 'content-type: text/plain;' \
     http://192.168.1.50/
   ```

This approach enhances security by centralizing authentication and enabling request filtering.

### Useful Resources

* **Build Documentation**:
  * [README.md](https://github.com/qtumproject/qtum/blob/master/README.md)
  * [build-unix.md](https://github.com/qtumproject/qtum/blob/master/doc/build-unix.md)
  * [build-osx.md](https://github.com/qtumproject/qtum/blob/master/doc/build-osx.md)
  * [build-windows.md](https://github.com/qtumproject/qtum/blob/master/doc/build-windows.md)
* **Configuration**:
  * [qtum.conf examples](https://github.com/qtumproject/qtum/blob/master/contrib/debian/examples/qtum.conf)
* **macOS Specific**:
  * [macOS Code Signing Guide](https://github.com/qtumproject/qtum/blob/master/doc/macOS-Sign-Qtum-Qt.md)
* **Command References**:

  ```bash
  ./qtumd -help           # View all daemon options
  ./qtum-cli help         # List all RPC commands
  ./qtum-cli help <cmd>   # Get help for specific command
  ```
* **CMake Build System**:

  ```bash
  cmake -B build -LH      # List all CMake configuration options
  ```
* **Official Resources**:
  * [Qtum GitHub Repository](https://github.com/qtumproject/qtum)
  * [Qtum Documentation](https://docs.qtum.info/)
  * [Release Notes](https://github.com/qtumproject/qtum/releases)