QuickBooks Desktop On-Premise Setup

QuickBooks Desktop runs locally and can’t be accessed directly from the cloud. To sync data from it, you need two things running on your network:

1. CData QuickBooks Desktop Gateway — A Windows service that exposes QuickBooks data over HTTP/HTTPS
2. Resplendent Sync Agent — A Docker container that connects to our cloud and relays sync requests to the Gateway

The sync agent connects outbound to Resplendent (no inbound firewall rules needed). When a sync runs, our cloud tells the agent what to fetch, the agent queries the Gateway, and sends the data back.

┌─────────────────────────────────────────────────────────────────┐
│                      Your local network                         │
│                                                                 │
│  ┌──────────────────┐         ┌──────────────────────────────┐  │
│  │   Linux VM       │  HTTP   │   Windows machine            │  │
│  │   (Sync Agent)   │◄───────►│   (QuickBooks + Gateway)     │  │
│  └────────┬─────────┘         └──────────────────────────────┘  │
│           │                                                     │
└───────────│─────────────────────────────────────────────────────┘
            │ WebSocket (outbound only)
            ▼
    ┌───────────────────┐
    │  Resplendent      │
    │  Cloud            │
    └───────────────────┘

---

Part 1: Create a sync agent in Resplendent

1. Log in to Resplendent at https://app.resplendentdata.com
2. Go to Data Settings → Sync Agents in the left sidebar
3. Click the Add button (top right of the table)
4. Enter a name for your agent (e.g., “Office Sync Agent”)
5. Click Save

After saving, the page shows your Agent UUID and Agent Key. Copy both — you’ll need them when installing the agent.

The Agent Key appears after the first save and remains accessible on this page for future reference.

---

Part 2: Install the sync agent

Requirements

• Linux server (Ubuntu 20.04+ or similar)
• Docker and Docker Compose installed
• Network access to your Windows machine running QuickBooks

The agent also runs on any machine with Docker, including Windows with WSL2 or macOS. We recommend a dedicated Linux VM because it’s easier to keep running 24/7.

Quick install

SSH into your server and run:

mkdir resplendent_sync_agent
cd resplendent_sync_agent
curl -sSL https://app.resplendentdata.com/api/public/sync-agent-install.sh | bash

The script prompts for your Agent UUID and Agent Key. It creates a docker-compose.yaml and starts the agent.

Manual install

If you prefer not to pipe scripts to bash, create docker-compose.yaml manually:

services:
  sync-agent:
    image: resplendentdata/sync-agent:latest
    container_name: sync-agent
    environment:
      - SYNC_AGENT_UUID=your-uuid-here
      - SYNC_AGENT_KEY=your-key-here
    labels:
      - 'com.centurylinklabs.watchtower.enable=true'
    restart: always

  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_RESTARTING=true
      - WATCHTOWER_ROLLING_RESTART=true
      - WATCHTOWER_POLL_INTERVAL=21600
    dns:
      # Watchtower needs public DNS to resolve Docker Hub for image updates
      - 8.8.8.8
      - 1.1.1.1
    restart: always

Replace the UUID and Key values, then run:

docker compose up -d

Watchtower checks for updates every 6 hours and restarts the agent automatically when new versions are released.

Verify it’s working

docker compose logs -f sync-agent

You should see:

INFO:__main__:Authenticating with server
INFO:__main__:Successfully authenticated with the server

Back in Resplendent, the Last Connection field on the Sync Agents page should update to show the current time. The agent sends a heartbeat every 30 seconds.

---

Part 3: Install the CData Gateway (Windows)

Requirements

• Windows machine where QuickBooks Desktop is installed
• QuickBooks Desktop must be running during syncs
• Administrator access

Installation

1. Download the CData QuickBooks Desktop Gateway from: https://www.cdata.com/products/quickbooksgateway/

2. Run the installer

3. The Gateway Control Panel opens after installation. If not, find “CData QuickBooks Desktop Gateway” in the Start Menu.

---

Part 4: Configure the Gateway

Create a Gateway user

1. Open the CData QuickBooks Desktop Gateway
2. Go to the Users tab
3. Click Add User
4. Enter a username (e.g., resplendent) and a password
5. Click Save

Write down the username and password. You’ll enter these in Resplendent later.

Configure the service

1. Go to the Service tab
2. Note the Port (default: 8166)
3. SSL is not required for local connections — the sync agent runs on the same network, so HTTP is fine
4. Note the URL shown (e.g., http://192.168.1.100:8166)
5. Click Start Service

Authorize QuickBooks access

1. Open QuickBooks Desktop as an administrator
2. In the Gateway, go to the Connection tab
3. Click Connect to QuickBooks
4. QuickBooks shows an authorization prompt — select “Yes, always allow access”
5. Verify the status shows “Connected”

QuickBooks must be open and logged in whenever a sync runs. If it’s closed, syncs will fail with a “QuickBooks not responding” error.

---

Part 5: Connect in Resplendent

1. In Resplendent, go to Data Settings → Integrations
2. Find QuickBooks Desktop and click Connect
3. Enter your Gateway details:
   • Gateway URL: The URL from Part 4 (e.g., http://192.168.1.100:8166)
   • Username: The Gateway user from Part 4
   • Password: The password you created
4. Scroll down to On-Premise Sync Agent
5. Toggle Enable On-Premise Sync
6. Select your sync agent from the list
7. Click Save & Test

If the test succeeds, you’ll see a green “Connected” status. Click Sync Dataset to choose which QuickBooks tables to sync.

---

Managing the sync agent

Common commands (run from the directory containing docker-compose.yaml):

# View logs
docker compose logs -f sync-agent

# Restart the agent
docker compose restart sync-agent

# Stop the agent
docker compose down

# Pull latest version manually
docker compose pull && docker compose up -d

---

Troubleshooting

”Network unreachable” or connection timeout

• Verify the Linux VM can reach the Windows machine: ping <windows-ip>
• Check Windows Firewall allows inbound connections on port 8166
• Make sure the Gateway service is running (check the Service tab)

“Authentication failed”

• Verify the username and password match what you created in the Gateway
• Check the Gateway URL matches (http vs https if you enabled SSL)

“QuickBooks not responding”

• Make sure QuickBooks Desktop is open and logged into a company file
• Verify the Gateway shows “Connected” in the Connection tab
• Try clicking Connect to QuickBooks again in the Gateway

Sync agent not connecting

• Check Docker is running: docker ps
• Verify the UUID and Key in docker-compose.yaml match what’s in Resplendent
• Check logs for authentication errors: docker compose logs sync-agent

Agent shows “Never connected” in Resplendent

• The agent might not have started. Check docker compose ps
• Outbound WebSocket connections might be blocked. The agent connects to wss://app.resplendentdata.com on port 443
• DNS issues: try adding dns: [8.8.8.8, 1.1.1.1] under the sync-agent service

---

Security notes

1. HTTP is fine for local connections — The sync agent runs on your local network, so HTTPS isn’t required. If you prefer encryption, you can enable SSL in the Gateway settings.
2. Restrict Gateway access — Configure Windows Firewall to only allow the sync agent’s IP on port 8166
3. Use strong passwords — The Gateway user password protects access to your QuickBooks data
4. Keep software updated — The sync agent updates automatically; update QuickBooks and the Gateway manually
5. Docker socket access — Watchtower mounts the Docker socket (/var/run/docker.sock) to manage container updates. This grants Watchtower privileged access to control containers on the host. Some enterprise security policies may prohibit socket access. If you need manual update control, remove the watchtower service from docker-compose.yaml and run docker compose pull && docker compose up -d to update manually.

The sync agent only makes outbound connections. It doesn’t open any inbound ports or accept incoming connections.

---

Support

If you’re stuck, email support@resplendentdata.com with:

• Sync agent logs (docker compose logs sync-agent)
• Screenshot of the Gateway’s Connection tab
• Any error messages from the Resplendent UI

---

Related topics

• QuickBooks integration overview
• Managing synced datasets
• Data Settings overview