Installation

Apphold is an open-source, self-hosted software telemetry and uptime monitoring platform that can be installed and run on web servers. Users will be able to reach the application through their web browsers by using an active internet connection. The installation process is very similar to the one required by the popular PHP framework Laravel.

Server Requirements

  • Apache / Nginx
  • MySQL
  • PHP >= 8.2
  • BCMath PHP Extension
  • Ctype PHP Extension
  • Fileinfo PHP Extension
  • JSON PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PDO PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension
  • Zip PHP Extension (required for auto-updates)

Tip: Most shared hosting providers already have these extensions enabled. If you're unsure, create a phpinfo.php file with <?php phpinfo(); ?> and open it in your browser to verify.

Steps

Apphold requires a few steps and minimum configuration for the installation to your server.

  1. Download the latest release archive from the Apphold GitHub Releases page.
  2. Upload the contents of the zip archive to your server via FTP, SFTP, or SSH.
  3. Make sure the web server is configured to only serve the public directory.
  4. Create an .env file based on the .env.example provided and enter your configuration values (database host, name, username, password, app URL).
  5. Run php artisan migrate:fresh --seed to set up the database tables and create the initial admin account.
  6. Open your browser and navigate to your configured domain. Log in with the default credentials (admin@example.org / 12345678) and change the password immediately.

Alternatively you can open the browser to the /url/to/public/setup.php file and submit the installation form, which handles the database setup automatically.

Web Server Configuration

Apache

If you're using Apache, ensure mod_rewrite is enabled and AllowOverride All is set for the application directory. A sample virtual host configuration:

<VirtualHost *:80>
    ServerName telemetry.example.com
    DocumentRoot /var/www/apphold/public

    <Directory /var/www/apphold/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx

For Nginx, configure the root to point at the public directory and add a try_files directive:

server {
    listen 80;
    server_name telemetry.example.com;
    root /var/www/apphold/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Important: Make sure the entire application directory is completely writable by the PHP process so that the auto update feature works properly.

Setting File Permissions

After uploading the files, set the correct permissions so that the web server can read and write as needed:

# Set ownership to the web server user (e.g. www-data)
sudo chown -R www-data:www-data /var/www/apphold

# Set directory permissions
sudo find /var/www/apphold -type d -exec chmod 755 {} \;

# Set file permissions
sudo find /var/www/apphold -type f -exec chmod 644 {} \;

# Ensure storage and cache are writable
sudo chmod -R 775 /var/www/apphold/storage
sudo chmod -R 775 /var/www/apphold/bootstrap/cache

HTTPS / SSL Configuration

It is strongly recommended to serve Apphold over HTTPS to ensure secure communication between your monitored services and the platform. You can use Let's Encrypt for free SSL certificates:

# Install Certbot (Ubuntu/Debian)
sudo apt install certbot python3-certbot-apache   # for Apache
sudo apt install certbot python3-certbot-nginx     # for Nginx

# Obtain and install certificate
sudo certbot --apache -d telemetry.example.com         # for Apache
sudo certbot --nginx -d telemetry.example.com          # for Nginx

Useful Links