Install Nuvabill in about 15 minutes

Install with one command

On a fresh Ubuntu 22.04 or 24.04, or Debian 12 or 13 server, sign in as root and run:

curl -fsSL https://nuvabill.com/install.sh | bash

It installs Nginx, PHP 8.4 and MariaDB, creates the database, gets a free SSL certificate from Let's Encrypt, adds the cron job, and then asks for your company name and your owner account. Point your domain at the server first. To give the address up front:

curl -fsSL https://nuvabill.com/install.sh | bash -s -- --domain billing.yourhost.com

On a server that already runs PHP 8.3 or newer, for example over SSH or in cPanel → Terminal, the same command installs Nuvabill into a nuvabill folder, asks a few questions and adds the cron job. Choose another folder with --dir, then point your domain at its public folder.

Every download is checked against the Nuvabill release signature before anything is unpacked. Already unpacked Nuvabill yourself? Run php artisan nuvabill:install in its folder to install from the terminal. You can read the script first at GitHub.

No terminal on your hosting? Follow the steps below instead.

1. Check your hosting

• PHP 8.3 or newer (8.4 works too)
• PHP extensions: pdo, openssl, mbstring, tokenizer, xml, ctype, json, fileinfo, curl, zip, intl, sodium and bcmath
• A database: MySQL 8 or MariaDB 10.6+. SQLite is fine for testing and small sites.
• Cron jobs that can run every minute

In cPanel, choose the PHP version in Select PHP Version or MultiPHP Manager, and turn on missing extensions there. The installer checks everything and tells you what is missing.

2. Upload Nuvabill

1. Download nuvabill-x.y.z.zip from the latest release on GitHub.
2. In cPanel, create a domain or subdomain, for example billing.yourhost.com. Set its document root to a new folder and add /public at the end, for example billing.yourhost.com/public.
3. Open File Manager, go to that folder (not the public folder inside it), upload the zip and choose Extract.
4. In cPanel, create an empty MySQL database and a user, and give the user all privileges on the database.

3. Run the web installer

Open your domain in a browser. The installer:

1. checks your PHP version, extensions and folder permissions,
2. connects to the database you created,
3. asks for your company name and email,
4. creates your owner staff account.

When it finishes, the installer closes itself. Sign in to the admin area at /admin.

4. Add the cron job

One cron job runs everything: renewal invoices, reminders, suspensions, email and updates. In cPanel open Cron Jobs, choose Once Per Minute and add this command. The exact line for your server is shown in the admin area under Settings → Automation.

cd /home/USER/billing.yourhost.com && /usr/local/bin/php artisan schedule:run >> /dev/null 2>&1

The dashboard warns you if the cron job stops running.

5. Connect your business

1. Servers: add your cPanel/WHM, DirectAdmin, Plesk, Virtualizor or Proxmox server and press Test connection. For CyberPanel, HestiaCP, VirtFusion or SolusVM, install the free module from Marketplace first.
2. Products: create your plans, set prices for each billing cycle and choose the package or VPS plan.
3. Settings → Domains: set your domain prices. Setup → Extensions → Registrars: connect your registrar account.
4. Setup → Extensions → Payment gateways: turn on the gateways you use. Add the webhook address that Nuvabill shows you in the gateway’s account.
5. Settings → Sending email: add your SMTP details and send yourself a test email.
6. Settings → Security: choose your two-factor and CAPTCHA rules. Then turn on two-factor login in Your profile.

Your store is now live at your domain. Place a test order to see the full flow: order, invoice, payment and account setup.

Control panels and VPS

• cPanel & WHM: username root (or a reseller) and a WHM API token.
• DirectAdmin: your admin or reseller name and a login key (DirectAdmin → Login Keys). Fill in the server’s IP address for new accounts.
• Plesk: an API key made with plesk bin secret_key -c, or the admin username and password. Products use a Plesk service plan name.
• Virtualizor: the Admin API key and API password (Configuration → Server Info), and allow your Nuvabill server’s IP. Products use a Virtualizor plan ID and an OS template ID.
• Proxmox VE: an API token (Datacenter → Permissions → API Tokens). New servers are cloned from a cloud-init template you choose on the product.

Free on the Marketplace (install first, then choose it on Servers → Add server):

• CyberPanel: a CyberPanel admin username and password with API access turned on (Users → API Access). Port 8090. Products use a CyberPanel package, PHP version and website limit. Clients sign in with one click.
• HestiaCP: an access key as ACCESS_KEY:SECRET_KEY in API token, and allow your Nuvabill server’s IP under Server settings → Security → API. Port 8083. Products use a Hestia package.
• VirtFusion: your panel’s hostname and an API token (Settings → API). Products use a package ID, hypervisor group ID and operating system ID.
• SolusVM: the API ID as username and the API key as API token (Configuration → API Access), and allow your Nuvabill server’s IP. Port 5656. Products use a node group, plan and OS template.

For Virtualizor and Proxmox, your customers manage their VPS on the service page in the client area: start, stop, restart, usage, IP addresses, root password and (Virtualizor) OS reinstall and VNC. VirtFusion and SolusVM servers get power controls too, and SolusVM adds hostname, root password and VNC. Your API keys never leave your server.

On the Marketplace: free Hetzner Cloud and Hetzner Dedicated (Robot) modules, and Proxmox VE Servers and DigitalOcean Servers for a full server panel with a browser console. To sell your own dedicated servers, add them on the Hardware page; power control, switch ports and automatic OS installs are add-ons. See the Hardware guide.

Sell domains

1. Settings → Domains: add each extension (.com, .net…) with its register, transfer and renew price.
2. Setup → Extensions → Registrars: turn on ResellerClub, Namecheap, Enom or OpenSRS and add your API details. Most registrars only accept API calls from IP addresses you allow, so allow your server’s IP.
3. Choose the registrar for each extension. Domains are registered when the invoice is paid, renewed before they expire, and customers change nameservers themselves.

Without a registrar, the domain search still works (it asks the free RDAP service), and you register domains by hand.

Payment gateways

Built in: Stripe, PayPal and bank transfer, and Iraqi payments with FIB (First Iraqi Bank, customers scan a QR code), FastPay and Wayl. Stripe and PayPal payments can be refunded from the invoice page. Each gateway’s settings page shows the webhook or return address to add in its merchant account.

Automatic payments: clients can save a card (Stripe) or a PayPal account when they pay, or in Account → Payment methods, and the nightly job charges their renewal invoices, after using any wallet credit. Failed charges are tried again after 3 and 7 days. Set it up in Settings → Automatic payments. For PayPal, turn on Save payment methods for your app at developer.paypal.com first. The full guide is in docs/automatic-payments.md.

Import from WHMCS, Blesta, FOSSBilling or Paymenter

1. Install Nuvabill first (a fresh install is best).
2. Open Settings → Import, choose the system you are leaving and enter its database details (from WHMCS’s configuration.php, Blesta’s config/blesta.php, FOSSBilling’s config.php or Paymenter’s .env). If it is on another server, allow your Nuvabill server in Remote MySQL there.
3. For WHMCS, you can add the encryption key ($cc_encryption_hash) so server and service passwords come across too. For Blesta, add the system key (Blesta.system_key) so clients keep their passwords.
4. Press Save and check. Nuvabill makes a dry run: it shows what would be imported and any problems, without changing anything. Then press Start import. It runs in the background from the cron job.

Imported: staff, clients (they keep their passwords), product groups, products and prices, servers, services, domain prices, domains, invoices, payments, wallet credit, support departments and tickets. The other system is only read. Run the import again just before you switch: it adds new records and updates changed ones without making copies. Afterwards, check your servers, switch on the ones Nuvabill should use, and turn off automation in the old system. On the command line: php artisan nuvabill:import whmcs --dry-run (or blesta, fossbilling, paymenter).

Two-factor, CAPTCHA and social sign-in

• Settings → Security: make two-factor sign-in optional or required for staff and for customers. Customers can use an authenticator app or get codes by email.
• CAPTCHA: choose Cloudflare Turnstile (free), Google reCAPTCHA or hCaptcha, add the keys and choose the forms. Solve it once on the settings page to turn it on, so wrong keys can never lock you out.
• Settings → Social login: let customers sign in with Google, GitHub or Facebook. Copy the redirect address shown there into the provider’s app settings.
• Fraud checks hold new orders for review when the email address is a throwaway one, one IP places too many orders, or the visitor’s country does not match.

Automations

An automation is a rule: when this happens, and these conditions are true, do these steps. Open Automations in the admin area and start from one of nine templates, for example Late fee after 7 days or VIP tickets first.

• What starts it: a client signs up, an order is placed, an invoice is paid, due soon or overdue, a service is set up, suspended, terminated or has been active for a while, a domain expires soon, a client opens or replies to a ticket, or a quote is not answered. Starting points with a number of days are checked once a day from 9:00.
• Conditions: the client’s tags, country, paid invoices, active services and open tickets, and the invoice, order, service, ticket, quote or domain itself.
• Steps: email the client or staff (with placeholders like {{ client.first_name }} and {{ invoice.url }}), add a fee to the invoice, add wallet credit, tag or untag the client, open, assign or prioritise a ticket, suspend or unsuspend the service, send the details to an HTTPS web address as JSON, wait hours or days, and only go on if something is still true.

A new automation is off until you switch it on. Use Try it with a real invoice number or client email first: it shows what each step would do, and nothing changes. Automations → Runs shows every run. A waiting run stops by itself when what started it is no longer true, for example when the invoice was paid. Automations use the cron job you already have. The full guide is in docs/automations.md.

AI help

Nuvabill uses Claude by Anthropic with your own key to draft ticket replies, translate tickets both ways, summarize tickets and write product texts. You pay Anthropic for what you use; Nuvabill adds nothing.

1. Make an API key at console.anthropic.com → API keys, and add some credit there.
2. Open Settings → AI, paste the key, pick a model (Claude Haiku 4.5 is fast and low cost; Sonnet 5.5 and Opus 5.5 give better answers for more money) and set a monthly limit. Press Test the key.
3. On a ticket, press Write a draft, then check it and send it. Staff always send; AI never replies by itself.

Email addresses, phone numbers, card and bank numbers, passwords and keys are taken out before anything goes to the AI. Staff see AI buttons when their role has the right “Use AI help for ticket replies and product texts”. The full guide is in docs/ai-help.md.

Telegram and WhatsApp

Nuvabill sends invoices, reminders, payment receipts and ticket replies to clients on Telegram and WhatsApp, next to the email. Everything is in Settings → Chat apps.

1. Telegram: in Telegram, open @BotFather, send /newbot and paste the token it gives you. Add the bot to your team’s group for staff alerts.
2. WhatsApp: press Connect with a QR code, sign in with Facebook and scan the code with the WhatsApp Business app. Your number keeps working in the app. Businesses with their own Meta app can enter its details instead.
3. Pick which messages go to which app. Clients link their chat app by scanning a QR code on their Account page in the client area.

Linked clients can send /invoices, /services and /tickets; anything else they write becomes a ticket, and your answer goes back to the chat. Telegram is free. Meta charges a small fee for WhatsApp messages you send first, and those use templates Meta approves. The full guide is in docs/chat-apps.md.

Admin phone app

Staff can install the admin area as an app on their phone, from the browser, with no app store.

1. Open Your profile → Phone app. On a computer, scan the QR code there with your phone to open the admin area on it.
2. On iPhone and iPad: in Safari, tap Share, then Add to Home Screen. On Android: in Chrome, open the menu, then Install app.
3. Open the app, go to Your profile → Phone app again and press Turn on alerts on this device. Choose which alerts you want: new orders, payments, new tickets and client replies.

The app opens on a Today screen with the day’s orders, payments, open tickets and overdue invoices, and what needs you. Alerts need the cron job and a site address that starts with https://. The full guide is in docs/phone-app.md.

Search engines

Nuvabill tells Google, Bing and link preview apps what is on your store, with every theme and nothing to install:

• Titles and descriptions for every store page. Products use their features (one per line in the description) and their lowest price.
• sitemap.xml and robots.txt, made and kept up to date for you. Send https://your-store/sitemap.xml to Google Search Console and Bing Webmaster Tools.
• Prices on Google, links between language versions (?lang=de) and link previews with your share image.
• One address per page, from APP_URL in .env. Make sure it is your real store address with https://.

Go to Settings → Search engines for your home page text, the share image (1200 × 630 pixels), the Google and Bing codes and your own robots.txt lines. Each product and group has a Search appearance box with a Google preview. Site health → Search engines checks it all every night.

Using Cloudflare

If your site is behind Cloudflare, add this line to the .env file in the Nuvabill folder, so sign-in limits and logs see your visitors' real IP addresses:

NUVABILL_TRUSTED_PROXIES=cloudflare

Use the Full (strict) SSL mode in Cloudflare, with a valid certificate on your server (cPanel AutoSSL is enough).

If the Marketplace page says Cloudflare stopped your server from reaching the marketplace, click Connect to marketplace once. The store checks that you own your web address and lets your server through. It is free; see the marketplace guide.

Updates

Nuvabill checks for new versions every day. Go to Updates in the admin area and press Update now, or let security updates install themselves at night. Every update is signed; Nuvabill checks the signature, backs up your files and database, and rolls back if something fails.

Getting help

Found a problem or have a question? Open an issue on GitHub. The read me has more details, including how to write extensions and themes.