> For the complete documentation index, see [llms.txt](https://docs.uxwizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uxwizz.com/installation/setup-uxwizz-server/ubuntu-20.04.md).

# Ubuntu 24.04 LTS

Use the interactive `install.sh` script on a **fresh Ubuntu 24.04 LTS server**. It installs Apache, PHP, MariaDB, and UXWizz, and sets up scheduled tasks.

{% hint style="info" %}
You need SSH access and `sudo` or root permissions. You do not need to create a database, choose a database password, or prepare an environment file for a normal installation.
{% endhint %}

## Steps summary:

1. Check the [prerequisites](#lamp-setup) and [network access](#basic-security).
2. [Run the installer and follow its prompts](#installing-uxwizz).
3. [Enable HTTPS](#adding-your-domain-name).
4. [Create the administrator and check tracking](#finish-and-check-the-installation).

### Video walkthrough

[![Run the Linux installer, create your administrator and add the tracking code](https://www.uxwizz.com/videos/uxwizz-install-linux-guide-v14.webp?v=ac364f4bb6eb4f9b)](https://www.uxwizz.com/videos/uxwizz-install-linux-guide-v14.mp4?v=9e31b9473a745e4e)

[Watch the Ubuntu installation video](https://www.uxwizz.com/videos/uxwizz-install-linux-guide-v14.mp4?v=9e31b9473a745e4e). [English captions](https://www.uxwizz.com/videos/uxwizz-install-linux-guide-v14.en.vtt?v=b6e2b82f8cddb2a5) are also available.

## LAMP Setup

Start with a fresh **64-bit Ubuntu 24.04 LTS** server. Its PHP 8.3 and MariaDB 10.11 packages meet the [UXWizz requirements](/installation/requirements.md). The default packages on Ubuntu 20.04 and 22.04 do not meet all current requirements.

Check the [server sizing guide](/installation/requirements/server-specs-cpu-ram.md) before choosing your server. Use a public hostname such as `stats.example.com`, with DNS pointing to the server. If you publish both A and AAAA records, both must point to addresses that serve this installation.

{% hint style="warning" %}
This script is for a **new installation**, not an upgrade. It needs an empty application destination and refuses existing UXWizz server configuration. To update an existing installation, back it up and use **Settings → Updates**. Use the [manual installation guide](/installation/installation.md) for an existing hosting account.
{% endhint %}

## Basic Security

Allow inbound TCP **80** and **443** in the server and hosting-provider firewalls. Keep your actual SSH port allowed. If you change firewall rules, confirm a second SSH connection works before closing the first.

The server needs outbound access to Ubuntu package repositories and HTTPS access to `www.uxwizz.com`, `license-api.uxwizz.com`, and `uxwizz.github.io`. Certificate setup also needs access to Let's Encrypt.

Keep database port **3306** closed to the public internet. The normal installation uses a local database with a dedicated application account.

If you manage the host firewall with UFW, check its current rules first:

```bash
sudo ufw status verbose
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
```

Replace `22` with your actual SSH port **before** running the commands. If UFW is inactive and you want to enable it, run `sudo ufw enable` only after checking the SSH rule and keeping your current connection open. Confirm a second SSH login works. Keep any other rules your server needs, and check the hosting provider's firewall separately.

## Installing UXWizz

1. Connect to the new server through SSH. If `curl` is missing, install it first:

   ```bash
   sudo apt update
   sudo apt install -y curl ca-certificates
   ```
2. Run the installer:

   ```bash
   curl -fsSL https://www.uxwizz.com/install.sh | sudo bash
   ```
3. Answer the prompts:
   * **Installation type (trial, regular, or agency):** press Enter for `trial`, or enter the type that matches your standalone license.
   * **Public hostname for the UXWizz dashboard:** enter `stats.example.com`, using your own hostname. Do not include `https://` or a path. Accept the detected name only if it is your intended public hostname.
   * **UXWizz license:** enter your license for a paid installation. The input is hidden. Trial installations skip this prompt.

The script installs UXWizz in `/var/www/uxwizz`, creates the local database and its user, and generates a database password and application encryption key. It verifies the downloaded package checksum and enables systemd timers for scheduled tasks.

{% hint style="info" %}
Runtime settings and secrets are stored in `/etc/uxwizz/uxwizz.env`, readable only by root. Back up this file securely with the database. Do not edit `server/dbconfig.php` for this installation or paste the environment file into support messages.
{% endhint %}

To inspect the script before running it, use this alternative instead of step 2:

```bash
curl -fsSLo uxwizz-install.sh https://www.uxwizz.com/install.sh
less uxwizz-install.sh
sudo bash uxwizz-install.sh
```

When the script prints **Installation files ready**, continue with HTTPS before entering the administrator password. If it stops with an error, follow [Common failures](#common-failures).

## Adding your domain name

Use the same hostname you entered during installation. Confirm its DNS records point to this server before requesting a certificate.

### Install certbot

For a server that receives web traffic directly, install Ubuntu's [Certbot Apache package](https://packages.ubuntu.com/noble/python3-certbot-apache) and request a certificate:

```bash
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache --redirect -d stats.example.com
sudo certbot renew --dry-run
```

Replace `stats.example.com` with your hostname. Follow the Certbot prompts. It configures HTTPS and an HTTP-to-HTTPS redirect. The last command checks certificate renewal.

Include only hostnames you use and that resolve to this server. Do not add `www.stats.example.com` automatically. For an apex domain that uses both `example.com` and `www.example.com`, supply both with separate `-d` options.

If a reverse proxy handles HTTPS, configure the certificate there and have the server administrator review the [advanced proxy settings](#reverse-proxies).

## Finish and check the installation

1. Open `https://stats.example.com/server/install.php`, using your own hostname. Confirm the browser shows no certificate warning.
2. The database is already configured. On **Create your administrator**, enter and confirm a password of at least 12 characters, then click **Create administrator**.
3. Sign in as **admin** with that password. There is no default password.
4. Add your website and [install its tracking code](/installation/adding-the-tracking-code.md). Visit a tracked page in another browser or private window, then check that the visit appears in UXWizz. If it does not, follow [No data is being recorded](/guides/troubleshooting/tracking/no-data-is-being-recorded.md).
5. Open **Settings → Scheduled Tasks**. Check **Next run** for active tasks, then check **Runs** after a task is due. A new installation can have no run history yet. The timers check for due tasks every five minutes and every hour; they wait until browser setup is complete. Do not add a second cron schedule for the same tasks.

## Common failures

| Problem                                                             | Next step                                                                                                                                                                  | Access needed                           |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| No terminal is available                                            | Run the command in an interactive SSH terminal. For automation, use the advanced section below.                                                                            | SSH                                     |
| Unsupported PHP, missing extension, or old database                 | Check the website's PHP runtime and database version against the requirements. Upgrade the affected server component; do not bypass the check.                             | Server or hosting panel                 |
| Download or checksum failure                                        | Check network access and retry only as the installer directs. If checksums still disagree, contact support. Keep HTTPS and checksum verification enabled.                  | SSH; support if it persists             |
| Existing configuration, database, account, or non-empty destination | Stop and identify the previous installation. Keep its data and credentials. Do not delete it to force a fresh install.                                                     | Server administrator                    |
| Database connection fails after running the script                  | Check the database service and the saved settings in `/etc/uxwizz/uxwizz.env`. Restore the correct connection; do not generate replacement secrets or edit `dbconfig.php`. | Server administrator                    |
| Apache fails, or the wrong page opens                               | Check the hostname, DNS, ports, and Apache virtual host. Use the commands below to inspect the error.                                                                      | Server administrator                    |
| Certificate request fails                                           | Check every requested hostname's DNS and inbound port 80. Correct the cause before retrying Certbot.                                                                       | DNS and server access                   |
| Permission error or directory listing                               | Check ownership, `.htaccess` handling, and the affected paths in the UXWizz virtual host. Do not apply world-writable permissions or change every site's Apache rules.     | Server administrator                    |
| Administrator passwords do not match or the form expires            | Enter matching passwords, or reload the setup page and submit it again.                                                                                                    | Browser                                 |
| No scheduled-task history                                           | Finish browser setup and check **Next run** for active tasks. If a task is overdue and **Runs** stays empty, check the timers and logs below.                              | UXWizz for status; SSH for timer repair |

Read-only server checks:

```bash
sudo apache2ctl configtest
sudo systemctl status apache2 mariadb --no-pager
sudo systemctl list-timers 'uxwizz-*' --no-pager
sudo journalctl -u 'uxwizz-scheduled-tasks@*' --since today --no-pager
```

If the installer reports saved recovery files or a partial application directory, preserve them and the database. Follow its recovery message or contact [support](/guides/support.md) before retrying. Remove passwords, license keys, tokens, and private user data from any log excerpts you share.

### Repair Apache .htaccess handling

If Apache ignores the supplied `.htaccess` files, first confirm that your upload included those hidden files. In the UXWizz virtual host, use a directory block limited to the actual installation:

```apache
<Directory "/var/www/uxwizz">
    Options -Indexes
    AllowOverride All
    Require all granted
</Directory>
```

Use your real application path. The current installer already configures this; manual or modified servers may need the repair. Do not replace every `AllowOverride None` in Apache's configuration.

Run `sudo apache2ctl configtest`, then `sudo systemctl reload apache2` only if it succeeds. Check the dashboard and confirm that `/server/` does not show a directory listing. A successful dashboard page alone does not prove that private files are protected.

## Advanced configuration

### Environment variables and unattended installation

Normal interactive installations do not need environment variables. For a new unattended trial installation, create this file in a private working directory outside the web root:

```bash
umask 077
cat > install.env <<'EOF'
UXWIZZ_NONINTERACTIVE=1
UXWIZZ_VARIANT=trial
UXWIZZ_SERVER_NAME=stats.example.com
EOF
```

Replace the hostname, download and inspect `uxwizz-install.sh` as shown above, then run:

```bash
sudo bash -c 'set -a; source ./install.env; set +a; exec bash ./uxwizz-install.sh'
```

The normal defaults still create the database, generate secrets, and configure scheduled tasks. Keep `install.env` private. For paid automation, set `UXWIZZ_VARIANT` to `regular` or `agency` and add the matching `UXWIZZ_LICENSE` to that protected file.

After installation, runtime changes belong in `/etc/uxwizz/uxwizz.env`. Server access is required. Preserve `UXWIZZ_APP_KEY` when restoring a backup; existing two-factor authentication secrets depend on it.

### Reverse proxies

If the public URL cannot be detected correctly, set `UXWIZZ_PUBLIC_SERVER_URL` to the full HTTPS URL ending in `/server`. Enable `UXWIZZ_TRUST_PROXY=1` only if the proxy is the only route to UXWizz and overwrites forwarded client-IP and protocol headers. It must preserve `Host` and forward `Authorization`.

After changing the runtime environment file, restart Apache so it loads the updated values:

```bash
sudo systemctl restart apache2
```