How to install external remote storage

Your main XFile Ultra server can store uploads on its own disk. That works when you are starting out. As traffic grows, keeping big files on the same machine as the website puts a lot of load in one place.

External remote storage fixes that. You add a second VPS that only handles files. Your main site stays lighter, and you can scale storage without rebuilding the whole product.

This guide walks through the full setup, then explains the options you will see after the node is connected (status, weight, performance mode, and more).

---

What this guide covers

There are three storage kinds in XFile Ultra:

This article is about the remote storage node — the usual “external remote storage” setup.

If you want object storage instead, see Add a CDN server (providers overview) and the provider-specific “How to Configure …” articles when you finish here.

---

What you need before you start

1. A working main website — XFile Ultra already installed and reachable over HTTPS. The storage package and registration token come from that site.

2. A second Linux VPS (Ubuntu or Debian) with root SSH access. This machine will only store and serve files.

3. A hostname for storage — for example files.yourdomain.com or storage.yourdomain.com.

4. DNS ready — an A record pointing that hostname to the storage VPS IP. Wait until DNS is live before you run the installer.

Tip: do not reuse the main site domain for the storage node. Give storage its own subdomain.

---

Overview of the steps

1. Create a storage server on the main site and download the package + token

2. Install the package on the storage VPS

3. Connect the node in the browser

4. Confirm it is On, healthy, and accepts a test upload

5. Tune options (performance mode, weight, limits)

---

Step 1 — Create the storage server on your main site

On the main website:

1. Sign in as admin

2. Go to Admin → Servers

3. Open Add storage server (provision page)

4. Enter a clear Server name (example: EU files or Storage node 1)

5. Click Create & get setup package

XFile Ultra creates:

The token usually expires after 7 days. If you lose it or it expires before you connect, open that server in Admin → Servers and use Regenerate setup token (only while the node is not connected yet).

Keep the zip and token ready. You will need both on the storage VPS.

---

Step 2 — Prepare the storage VPS

Connect to the storage server over SSH as root.

2.1 Confirm DNS

Make sure your storage hostname resolves to this VPS before you continue. If DNS is wrong, the setup script will stop.

2.2 Install unzip (if needed)

apt update
apt install -y unzip

2.3 Create the install folder

A common path is:

mkdir -p /var/xfileultra-storage/node
cd /var/xfileultra-storage/node

2.4 Upload and extract the package

Copy the zip from your computer into that folder (SCP, SFTP, FileZilla — whatever you prefer).

Then extract in place (the package usually unpacks flat into the current folder — you should not need an extra nested directory):

unzip -o xfileultra-storage-XXXXXX.zip

Replace the zip name with the file you downloaded.

---

Step 3 — Run the storage setup script

Still in the extracted folder:

chmod +x scripts/buyer-setup.sh
sudo ./scripts/buyer-setup.sh

When asked, enter your storage domain (the hostname with the A record).

The script typically:

• Checks DNS
• Installs Node.js and dependencies
• Sets up nginx and HTTPS
• Starts the storage service (often xfileultra-storage)
• Prints the install URL when it finishes

Defaults you will often see:

If the script fails on DNS, fix the A record, wait a few minutes, and run it again.

---

Step 4 — Connect the node to your main website

Open the URL the script printed, for example:

https://files.yourdomain.com/install

Fill in:

Click Test & connect (or the equivalent Connect button).

On success, the main site:

• Marks the server as connected
• Turns it On for new uploads (in normal cases)
• Stores the node secret and public URL
• Updates health to OK

Go back to the main site → Admin → Servers. The banner should move from “waiting for connection” to Connected.

If something fails, the usual causes are: expired token, wrong main site URL, storage path not writable, or the public URL not reachable over HTTPS.

---

Step 5 — Verify and run a test upload

On the main site:

1. Open Admin → Servers → Servers management

2. Find your new remote server

3. Confirm status is On and health looks healthy

4. Open Edit if you want to review settings

5. Use Test connection / health actions if available

6. Upload a small test file from the public upload page (or as a member)

If the upload lands on this server (or the Files count on that row moves), you are done with the install.

Existing files already on Local (or another server) stay where they are. Weight only affects new uploads. To move old files, use the transfer queue.

---

Understanding the options on a remote storage server

After the node is connected, open Admin → Servers → edit that server. These are the settings that matter day to day.

Status (On / Read-only / Off)

Use Read-only when you want to drain a server of new uploads but keep serving existing files. Use Off when the machine is down for maintenance.

Weight

Weight is the share of new uploads among eligible On servers. Higher weight = picked more often. It does not move old files and does not change download routing.

Example: Local weight 1, remote weight 3 → over time the remote tends to get about 75% of new uploads.

See Server Weight — how new uploads are shared for full examples.

Max disk usage

Optional cap for how much this server may hold. Empty / 0 usually means unlimited. When the cap is hit, the server stops taking new uploads even if status is On.

Who can upload to this server

You can limit the server to regular members, premium members, or a selected list of users. Combined with geo rules, this is how you keep EU files on an EU node, premium on a fast CDN, and so on.

GeoIP countries

Optional country allow/deny style targeting for uploads to this server. If an uploader’s country is not allowed, this server is skipped for that upload.

Public URL

The HTTPS base URL of the storage node. Required for health, registration, and especially for performance mode. It must match the certificate and hostname.

Performance mode (remote storage node)

On a remote node, performance mode is the option that says, in plain language:

> Deliver download & upload directly from this storage server (bypass the main website for the heavy bytes).

Notes that matter in production:

• This is not the same switch as CDN Performance mode. CDN has its own “direct upload and download” toggle for S3-style backends.
• For remote nodes, the direct-upload and direct-download behavior is tied to this performance / “deliver directly” control.
• If you see SSL errors on upload, check that the Public URL is HTTPS and the certificate matches the host.
• If traffic still seems to hit the main server, confirm the node is connected, healthy, performance mode is on, and the Public URL is correct.

SFTP on the node

Connected remotes can participate in member SFTP ingest when SFTP is enabled for that server and the member’s plan allows it. That is separate from the browser upload path. See SFTP on storage nodes if you need SSH file drop into the product.

---

Local vs remote vs CDN (quick decision guide)

You can run Local + remote + CDN together. New uploads are shared by weight among eligible On servers.

---

CDN performance mode (if you add object storage later)

When you add a CDN row under Add new CDN, you will see Performance mode → Direct upload and download (bypass main server).

Do not confuse this with remote-node performance mode. Same idea (bypass main server), different backend.

---

After install checklist

• [ ] Storage hostname A record points at the storage VPS
• [ ] Package installed with buyer-setup.sh as root
• [ ] /install connect succeeded with main URL + token
• [ ] Server shows Connected and On in Admin → Servers
• [ ] Test upload works
• [ ] Performance mode set the way you want (direct vs proxied)
• [ ] Weight set relative to Local / other servers
• [ ] Disk cap and member targeting reviewed

---

Common problems

Script stops on DNS

Wait until the storage hostname resolves. If you use Cloudflare, SSL mode Full / Full (strict) is the usual choice once certificates exist.

“Waiting for connection” forever

Token expired or already used, wrong main website URL, storage folder not writable, or public URL not reachable. Regenerate the token if the node is still not connected, then try /install again.

“This server is already connected or the setup token was used”

The token is one-time. After a successful connect you manage the node from Admin → Servers. You cannot reuse the old token.

Uploads never land on the new server

Check On, health OK, under disk cap, targeting/geo allows the member, and weight vs other On servers. A single test upload can still go to Local by chance when weights are equal — try a few uploads or raise the remote weight.

Performance mode on but traffic still hits the main site

Public URL / HTTPS problem, node secret missing, or the toggle is off. Re-test connection and confirm the edit form settings.

Looking for a nested folder after unzip

Extract in the install directory and run buyer-setup.sh from that same tree. The package is usually flat.

---

Related

• Storage backends overview (local vs remote node vs CDN)
• Provision a remote storage server (token + package)
• Install a storage node on a second VPS
• Connect and enable the storage node
• Direct upload on remote nodes
• Direct download on remote nodes
• Server Weight — how new uploads are shared
• Add a CDN server (providers overview)
• CDN Performance mode