Waterhole is a modern PHP application built on Laravel, and can be deployed like any standard Laravel application.
Running a copy of Waterhole on your computer is the preferred method for building and maintaining your community's features. This way you can keep your community's configuration and customization under version control, and easily test changes before you deploy them to production.
There are many ways to set up a local development server, from installing the stack from scratch, to using tools that do it for you like Laravel Valet. You can also run a Docker development environment using Laravel Sail.
The recommended way to deploy Waterhole in production is on a VPS, like those offered by DigitalOcean, Linode, and Vultr. This gives you full control over the server and the ability to scale up resources on demand.
Warning: While shared hosting can be easier to manage, it is often not possible to gain SSH access and use Composer, both of which are requirements for running Waterhole. For this reason, running Waterhole on shared hosting is not officially supported.
Once your production server is configured, clone your source control repository, and run:
Danger: In your production environment, ensure that
APP_DEBUGis set to
APP_ENVis set to
production. Otherwise, you risk exposing sensitive configuration values to your forum's users.
Whenever new changes are pushed into the repository, you can pull them in on your production server, then run:
composer install php artisan migrate php artisan waterhole:cache:clear
This will install the latest dependencies, update the database, and clear Waterhole caches.
Web Server Configuration#
The main things that need to be configured on the web server are:
- The document root, which should point to the
- URL rewriting to route all requests to the
Danger: Never attempt to move the
index.phpfile to your project's root, as serving the application from the project root will expose many sensitive configuration files to the public Internet.
You should also ensure that static assets are served with cache headers and Gzip compression to optimize the performance of your community.
Waterhole includes a
.nginx.conf file containing URL rewriting rules along with some additional best-practice performance configuration. You can manually copy this into your server block, or include it directly:
Waterhole includes a
.htaccess file containing URL rewriting rules along with some additional best-practice performance configuration. Make sure
mod_rewrite is enabled and
AllowOverride All is set.
Laravel offers various optimization mechanisms which can speed up your Waterhole installation in production. You should run these in your deployment script:
composer install --optimize-autoloader --no-dev php artisan config:cache php artisan route:cache php artisan view:cache
Waterhole also makes use of the Blade Icons library which has a caching mechanism that you should run in your deployment script:
php artisan icons:cache
Since Waterhole and the Laravel framework include a lot of PHP files, you can get a significant performance boost by enabling OPcache. If using Laravel Octane, ensure that the
opcache.enable_cli flag is on.
To supercharge your community's performance, you can use Laravel Octane. Refer to the Laravel documentation to learn more about how to set up Octane.