Deploying#
Waterhole is a modern PHP application built on Laravel, and can be deployed like any standard Laravel application.
Local Development#
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.
Production#
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.
Tip: Setting up and managing a VPS from scratch can be tedious. Consider using a service or tool that does this for you like Laravel Forge, Ploi.io, ServerPilot, or Deployer
Once your production server is configured, clone your source control repository, and run:
composer install
Then follow the rest of the Installation steps to establish your production Waterhole installation. Don't forget to add your license key as well!
Danger: In your production environment, ensure that
APP_DEBUGis set tofalseandAPP_ENVis set toproduction. 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.
With a service like Laravel Forge or a tool like Deployer you can even automate this process so deployments will automatically be triggered when you push changes to a particular branch.
Web Server Configuration#
The main things that need to be configured on the web server are:
- The document root, which should point to the
publicdirectory - URL rewriting to route all requests to the
public/index.phpfile
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.
Nginx#
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:
include /path/to/waterhole/.nginx.conf;
Apache#
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.
Optimization#
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
Icon Caching#
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
OPcache#
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.
Laravel Octane#
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.
No Results Found