Purpose:
This document helps customers resolve connection issues between DeskDay and a self-hosted Hudu instance, including API access errors, Cloudflare/WAF challenges, and relative URL issues.

Note: Use this guide only if you are experiencing connection errors or integration failures. The system shows an “unable to connect” or “authentication failed” or "Invalid Link or activation Key" message

Cloudflare / Proxy Configuration Requirements

Overview

If your Hudu server is behind Cloudflare DNS (orange cloud), certain Cloudflare features interfere with API access:

Bot protection
Browser/JS challenges
WAF security rules

Required Action

Disable Cloudflare Proxy (use DNS Only) for your Hudu domain.

Steps to Disable Cloudflare Proxy

Log in to Cloudflare Dashboard
Go to DNS → Records
Locate the A or CNAME record for Hudu
If the cloud icon is orange (Proxied), click it to turn grey (DNS Only)

Cloud modes:

Orange Cloud (Proxied): ❌ Not compatible with API integrations
Grey Cloud (DNS Only): ✔️ Required for API access

Why:
Disabling the proxy ensures API requests bypass bot protection, TLS termination, and header rewrites that break DeskDay integration.

Solutions for Cloudflare / WAF Blocking

Option 1 – Whitelist DeskDay in Cloudflare (Recommended)

Go to: Cloudflare → Security → WAF → Manage Custom Rules → Create Rule
Add:

Rule Name: Allow DeskDay Hudu API

WHEN:

HTTP Header "Origin" contains "hudu-api.deskday.ai" OR HTTP Header "Referer" contains "hudu-api.deskday.ai"

THEN:

Allow Skip WAF Skip Bot Fight Mode Skip Browser Integrity Check Skip Managed Challenge

Save → Deploy

This bypasses Cloudflare challenges for API traffic.

Option 2 – Provide Direct (Non-Cloudflare) Hudu URL

Use a direct origin (not behind Cloudflare), e.g.:

*.huducloud.com Internal DNS hostname

DeskDay will call:

GET <your-direct-origin-hudu-url>/api/v1/companies

Option 3 – Optional API-Only Subdomain

Create a dedicated subdomain, e.g.:

hudu-api.yourdomain.com

Configure it to:

Point to Hudu server
Bypass Cloudflare/WAF for /api/v1/*
Avoid JS/bot/browser challenges

DeskDay can use this exclusively for API calls.

Hudu URL Patch for API Compatibility

Some self-hosted Hudu environments run behind proxies/load-balancers, causing API serializers to generate incomplete URLs. This results in errors such as:

“Missing host to link to!”
DeskDay not able to fetch Companies, Articles, or other Hudu resources.

This guide provides a small patch that forces Hudu to always include a host/protocol when generating URLs — ensuring smooth connectivity with DeskDay.

Note: This patch works only if you follow Hudu’s standard self-hosted installation procedure:
Standard Setup Guide for Self-Hosted Hudu

1. What This Patch Fixes

These patches ensure:

Full URLs (with host + https) are generated in all API serializers.
DeskDay can fetch articles, companies, passwords, and shared URLs reliably.
Compatibility when Hudu is behind a reverse proxy (Traefik, Nginx, Cloudflare, etc.).

No business logic is changed — only URL generation.

2. Patch Bundle Contents

The integration bundle contains these files:

File	Purpose
docker-compose.yml	Mounts and loads the patch files into the Hudu app container.
zzz_host_patch.rb	Sets global `default_url_options` and patches `UrlFor` to always include a host.
zzz_serializer_patch.rb	Adds host/protocol options to `CompanySerializer` URL methods.
article_serializer.rb	Overrides `ArticleSerializer` to generate full URLs with host and protocol.
nginx.conf	Ensures correct forwarding headers (`X-Forwarded-Host`, `X-Forwarded-Proto`, etc.) for proper URL generation.

3. Installation Instructions

Follow these steps on your self-hosted Hudu server.

Step 1 - Place the Patch Files

Copy all these files into the same directory where your docker-compose.yml exists.

Example:

/hudu2/
  ├─ docker-compose.yml
  ├─ zzz_host_patch.rb  
  ├─ zzz_serializer_patch.rb
  ├─ article_serializer.rb
  ├─ nginx.conf
  └─ .env

Ensure the following variables are added in your .env file or directly in the container environment:
- HUDU_HOSTNAME
- DEFAULT_URL_HOST
- HOSTNAME

Step 2 – Update your `nginx.conf`

To ensure full URLs (with domain + protocol) are generated correctly in API responses, your NGINX setup must forward these headers:

Host
X-Forwarded-Proto
X-Forwarded-Port

If your Hudu is deployed using the official docker-compose.yaml:

You may have an nginx.conf file mounted into your NGINX service.
Alternatively, you might be using a reverse proxy like Traefik, NGINX Proxy Manager, Caddy, HAProxy, or a load balancer (AWS ALB / Cloudflare / NPM).

Below is the recommended NGINX configuration used in our internal Hudu test environment.
Please compare and patch your configuration accordingly.

Steps to update your NGINX configuration

Locate your nginx.conf (typically in the same directory as your docker-compose.yml).
Open it for editing:
```
sudo nano nginx.conf
```

Ensure the following headers exist inside BOTH / and /cable blocks:

proxy_set_header Host $host; 
proxy_set_header X-Forwarded-Proto https; 
proxy_set_header X-Forwarded-Port 443;

Save the file and restart your NGINX container:
```
sudo docker compose restart nginx
```

Step 3 - Add Volumes to Your docker-compose.yml

Update your app service as follows:

app:
 image: hududocker/hudu:latest   
 env_file: .env
 volumes:     
  - app_uploads:/var/www/hudu2/public/uploads     
  - ./zzz_host_patch.rb:/var/www/hudu2/config/initializers/zzz_host_patch.rb:ro     
  - ./zzz_serializer_patch.rb:/var/www/hudu2/config/initializers/zzz_serializer_patch.rb:ro

Note:
:ro makes the mounted patch files read-only for safety.

Step 4 - Restart Hudu

Run the following:

docker compose down 
docker compose up -d

This reloads the patches into the Hudu app container.

Step 5 — Patch ArticleSerializer

Hudu’s default installation does not include a host in article URLs, causing integrations like Helena AI to fail. Apply this patch to make URL generation deterministic.

1. Open a shell inside the Hudu app container:

sudo docker compose exec app sh

2. Edit the serializer file:

vi /var/www/hudu2/app/serializers/article_serializer.rb

3. Replace the entire file with the patched version provided.

4. Restart Hudu:

exit
sudo docker compose restart app worker

Validate

After the restart:

Open any Company in Hudu → confirm URLs load properly.
Open Articles → Sharing → ensure share URLs work.
Check DeskDay connection again — articles and companies should now sync.
Review logs (docker logs hudu-app) for any URL errors.

Rollback Instructions

Rollback Patch Files

If you want to revert:

Remove the 2 patch file volume mounts from your docker-compose.yml or delete

the patch files from the host.

- ./zzz_host_patch.rb:/var/www/hudu2/config/initializers/zzz_host_patch.rb:ro
- ./zzz_serializer_patch.rb:/var/www/hudu2/config/initializers/zzz_serializer_patch.rb:ro

Restart Hudu:

docker compose down 
docker compose up -d

Rollback Patch ArticleSerializer

Open a shell inside the Hudu app container:

sudo docker compose exec app sh

2. Edit the serializer file:

vi /var/www/hudu2/app/serializers/article_serializer.rb

3. Replace the entire file with the default article_serializer_default.rb version.

4. Restart Hudu:

exit
sudo docker compose restart app worker

Important Notes

General Notes

Patches are safe and non-destructive.
If you have heavy customizations or plugins, test in staging first.
Make sure these environment variables are set: HUDU_HOSTNAME, DEFAULT_URL_HOST, HOSTNAME.

Deployment Impact

Does not change the database, UI, migrations, or core functionality.
Does update how URLs are generated for API consumers (now full URLs instead of relative paths).

Final Notes

These patches do not modify your data or Hudu features.
Integrations using relative URLs may see formatting changes, but everything continues to work.
Ensure that URLs in API responses are fully qualified (with https://hostname).
If you use other integrations, they will continue to work normal.

7. Patch File Contents (Reference)

Note: Replace <Your Hudu Hostname> with your actual Hudu hostname.

docker-compose.yaml

zzz_serializer_patch.rb

zzz_host_patch.rb

article_serializer.rb

article_serializer_default.rb

nginx.conf

Hudu API Connection Troubleshooting + Patch Guide

Cloudflare / Proxy Configuration Requirements

Required Action

Steps to Disable Cloudflare Proxy

Log in to Cloudflare Dashboard

Solutions for Cloudflare / WAF Blocking

Option 1 – Whitelist DeskDay in Cloudflare (Recommended)

Option 2 – Provide Direct (Non-Cloudflare) Hudu URL

Option 3 – Optional API-Only Subdomain

Hudu URL Patch for API Compatibility

1. What This Patch Fixes

2. Patch Bundle Contents

3. Installation Instructions

Step 1 - Place the Patch Files

Step 2 – Update your `nginx.conf`

Steps to update your NGINX configuration

Step 3 - Add Volumes to Your docker-compose.yml

Step 4 - Restart Hudu

Step 5 — Patch ArticleSerializer

Validate

Rollback Instructions

Important Notes

7. Patch File Contents (Reference)

Hudu API Connection Troubleshooting + Patch Guide

Cloudflare / Proxy Configuration Requirements

Required Action

Steps to Disable Cloudflare Proxy

Log in to Cloudflare Dashboard

Solutions for Cloudflare / WAF Blocking

Option 1 – Whitelist DeskDay in Cloudflare (Recommended)

Option 2 – Provide Direct (Non-Cloudflare) Hudu URL

Option 3 – Optional API-Only Subdomain

Hudu URL Patch for API Compatibility

1. What This Patch Fixes

2. Patch Bundle Contents

3. Installation Instructions

Step 1 - Place the Patch Files

Step 2 – Update your nginx.conf

Steps to update your NGINX configuration

Step 3 - Add Volumes to Your docker-compose.yml

Step 4 - Restart Hudu

Step 5 — Patch ArticleSerializer

Validate

Rollback Instructions

Important Notes

7. Patch File Contents (Reference)

Step 2 – Update your `nginx.conf`