# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qtum.info/qtum-documentation/qtum-deployment/guidance-on-qtum-deployment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.