Gruxi Web Server

Appearance

Lightweight PHP Hosting with Gruxi: A Docker-Based Example ​

Lightweight PHP Hosting with Gruxi

If you want a lightweight PHP server for a personal project, an internal tool, or a small team site, you usually do not need a full traditional stack on day one. In many cases, you just need something that can serve a few static files, forward PHP requests correctly, and stay easy to understand when you revisit it later.

Gruxi fits that use case well. It can serve the static part of the site directly, forward PHP requests to PHP-FPM, and keep the site configuration in one place through the built-in admin UI. Combined with Docker Compose, that gives you an easy PHP hosting setup that is quick to run locally and straightforward to move to a server later.

If you are searching for a lightweight PHP server, a Docker PHP Gruxi example, or an easy PHP hosting workflow that does not start with Apache or Nginx, this guide walks through the smallest practical setup.

A good use case for this setup ​

This example is aimed at sites that mix ordinary files with some added server-side PHP.

Typical examples include:

  • a personal project site with a contact or status endpoint
  • an internal dashboard with a few HTML pages and one PHP script
  • a simple prototype where you want Docker and PHP without building a larger stack first

For that kind of project, the main goal is usually not maximum flexibility. It is getting a small site online with minimal moving parts.

In the example below, Gruxi serves:

  • a static index.html page
  • a small PHP endpoint at hello.php

That is enough to show the full request flow while keeping the setup small.

Docker Compose example ​

Start with a project directory like this:

text
lightweight-php-site/
	docker-compose.yml
	gruxi/
		db/
		logs/
		certs/
	app/
		index.html
		hello.php

Then create this docker-compose.yml:

yaml
services:
	gruxi:
		image: ghcr.io/daevtech/gruxi:latest
		depends_on:
			- php-fpm
		ports:
			- "80:80"
			- "443:443"
			- "8000:8000"
		volumes:
			- ./gruxi/db:/app/db
			- ./gruxi/logs:/app/logs
			- ./gruxi/certs:/app/certs
			- ./app:/app/www-default:ro
		restart: unless-stopped
		networks:
			- appnet

	php-fpm:
		image: php:8.3-fpm-alpine
		working_dir: /var/www/html
		volumes:
			- ./app:/var/www/html:ro
		restart: unless-stopped
		networks:
			- appnet

networks:
	appnet:
		driver: bridge

Now add a small static page in app/index.html:

html
<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<title>Lightweight PHP Hosting with Gruxi</title>
</head>
<body>
	<h1>Small Site on Gruxi</h1>
	<p>This page is served directly as a static file.</p>
	<p><a href="/hello.php">Open the PHP endpoint</a></p>
</body>
</html>

And add app/hello.php:

php
<?php
declare(strict_types=1);

header('Content-Type: text/html; charset=utf-8');

echo '<h1>Hello from PHP on Gruxi</h1>';
echo '<p>This response came through Gruxi and PHP-FPM.</p>';
echo '<p>PHP version: ' . PHP_VERSION . '</p>';

This is intentionally small. Gruxi handles incoming traffic and static files, while PHP-FPM executes the PHP script.

Minimal Gruxi configuration ​

Once the containers exist, the Gruxi configuration is simple.

Start the stack:

bash
docker compose up -d

Then open the admin UI:

text
https://localhost:8000

Log in as admin. On first startup, Gruxi prints the initial password in the container logs. If you need it, run:

bash
docker compose logs gruxi

In the Gruxi admin UI, create or edit a site with these settings:

1. Add a Static File Processor ​

Set the processor priority to 1 and point Web Root to:

text
/app/www-default

This lets Gruxi serve index.html, CSS, JavaScript, images, and other static assets directly.

2. Add a PHP Processor ​

Set the processor priority to 2 and configure:

  • Served By: PHP-FPM
  • Local Web Root: /app/www-default
  • FastCGI IP:Port: php-fpm:9000
  • FastCGI Web Root: /var/www/html

Those path values are the key detail. Gruxi sees the files under /app/www-default, while PHP-FPM sees the same files mounted at /var/www/html.

3. Save and reload ​

Save the site configuration and reload it in the admin UI.

That is enough for this example. You do not need a more complex config just to host a small HTML and PHP site.

If you later add framework routing, you can also add the rewrite function OnlyWebRootIndexForSubdirs, but the simple example here does not require it.

Run the container and test the site ​

After saving the configuration, open the site in your browser:

text
http://localhost/

You should see the static homepage first.

Then open:

text
http://localhost/hello.php

You should see the PHP response and the current PHP version.

If the static page loads but the PHP page does not, check the PHP processor values first, especially:

  • FastCGI IP:Port
  • FastCGI Web Root
  • Local Web Root

For containerized PHP setups, the FastCGI Web Root mismatch is the most common mistake. It must match the path inside the php-fpm container, not the path inside the Gruxi container.

If you want HTTPS for local testing, keep port 443 published as shown above and configure TLS on the Gruxi site binding. For local development, a self-signed certificate is often enough. For a deployed site, point your domain to the server and configure TLS normally.

Why this is a lightweight option ​

This setup works well as easy PHP hosting because it stays small where it matters:

  • Gruxi is one server binary in the front-end role
  • Static files and PHP routing are configured in one place
  • Docker Compose keeps the setup reproducible
  • You can add HTTPS without introducing another full server layer

That does not mean it replaces every larger stack. It means small projects do not have to start with more infrastructure than they need.

For developers who want a Docker PHP Gruxi workflow that is clear, practical, and low-maintenance, this is a good starting point.

Browse your site on Gruxi ​

This example shows the core idea: a small site with static files and a PHP endpoint can be hosted on Gruxi with very little setup. You get a lightweight PHP server, an admin UI, direct static file serving, and a standard PHP-FPM integration model that is easy to reason about.

If you want to keep going, the most useful next references are the Docker getting started guide, the PHP on Linux example, the PHP processor documentation, and the site processors documentation.

Browse your site on Gruxi. It is this easy.