A server for debugging more than just Laravel applications.

6 min readAug 25, 2021

I had to change the name of the server from RayServer to Buggregator because of collision with Ray app

Just a month ago, I came across a curious app Ray from spatie— an application with a minimalist interface for displaying debug information (values of variables, errors, logs, etc.) during application development.

The Ray app isn’t bound to specific framework, programming language or environment. In the PHP world the application works with spatie/ray package. There are also packages and libraries in other languages that work with the Ray app.

I wanted to see how it works from the inside, and I liked the idea so much that I developed a working analogue, which has almost all the functionality of the original, as well as additional features. I named it the Ray server.

The Ray server is a free alternative for those who want to run a server without GUI, cannot afford the paid version or just like open source.
But it doesn’t mean you shouldn’t support spatie’s packages!

How, what and why

As I said, the Ray app isn’t bound to a specific framework and programming language and is a multipurpose tool. However I wanted to make it a little different, similar to MailHog. If someone doesn’t know about MailHog — it is an SMTP-server for receiving test emails during development, which can be run in seconds via Docker and doesn’t require additional settings from the project’s side. I wanted the RayServer to have the same ability — run via Docker and easily be able to become a part of any project, even if there is an OS without GUI.

Technical aspect of the Ray app

The Ray app receives events and logs from various sources, and then displays them in a nice looking way, providing detailed information for each type of event.

At the same time it works quite simply:

When the Ray app starts, it launches a web server on port 23517.
spatie/ray package sends requests via HTTP to the Ray app and events display in the application window.

It looked understandable, and I thought: “Why not try to develop something similar, only in the form of a web server?” I also wanted to use a simple stack of technologies, just Laravel and Docker.

So, I set the following tasks for the Ray server:

display variables, logs and errors — this is one of the main features;
be free for everyone (Open Source project);
be extendable by contributors;
ease of use during development;
independence from the programming language and framework.

The result

I managed to complete all the tasks that I set at the beginning of my journey into the magical world of debugging. I developed an open source application — the RayServer, which displays events in a beautiful, readable way and solves the main problem of application debugging. At the same time the server is as simple as possible, and everyone can contribute to it.

Some of the RayServer features

Displaying variables

Marking events with additional colors and labels

Showing database queries [Laravel]

Showing fired Events [Laravel]

Showing cache events [Laravel]

Displaying mailables [Laravel]

Rendering views [Laravel]

Dispaying .env variables [Laravel]

Handling models [Laravel]

Showing backtrace

Displaying application errors.

The RayServer API is compatible with Sentry, making it a lightweight alternative for local development.

Displaying monolog logs

The RayServer is compatible with monolog/monolog composer package, and can display logs from it.

Catching SMTP mail

The RayServer also is an email testing tool that makes it super easy to install and configure a local email server. The RayServer sets up a fake SMTP server and you can configure your preferred web applications to use RayServer’s SMTP server to send and receive emails. For instance, you can configure a local WordPress site to use RayServer for email deliveries.

The RayServer has a lightweight and nice UI that allows you to view events, filtering them by label, type and color.

The RayServer is fully compatible with all features of the spatie/ray and spatie/laravel-ray packages.

UI has a responsive design and a mobile device can be used as an additional screen for viewing event history.

The RayServer is written on Laravel + Octane HTTP/Websocket and is open source under the MIT license. Anyone can contribute to it.

Code examples can be found here.

Installing and running the RayServer

Docker

The easiest way to run the RayServer is a Docker container. After running the docker container, the server is ready to receive events, and doesn’t require any additional configuration.

// Latest version
docker run --pull always -p 23517:8000 -p 1025:1025 butschster/debugger:latest// Specific version
docker run -p 23517:8000 -p 1025:1025 butschster/debugger:v1.15.2

A dashboard is available at http://127.0.0.1:23517

By default, the RayServer uses sqlite database for storing events. Furthermore, you can use an external database:

// docker-compose.yml
version: "2"
services:
    php:
        image: butschster/debugger:latest
        environment:
            DB_CONNECTION: pgsql
            DB_HOST: db
            DB_DATABASE: homestead
            DB_USERNAME: homestead
            DB_PASSWORD: secret
        ports:
        - 23517:8000
        - 1025:1025
        depends_on:
            - db    db:
        image: postgres
        environment:
            POSTGRES_USER: homestead
            POSTGRES_DB: homestead
            POSTGRES_PASSWORD: secret

Configuring packages to work with the RayServer

spatie/ray

It uses port 23517 by default and there is no need for additional configuration.

// For Laravel
RAY_HOST=127.0.0.1
RAY_PORT=23517

sentry

The RayServer is compatible with https://sentry.io/, so you can specify DSN in your application:

// Laravel
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:23517/1

monolog

There is a \Monolog\Handler\SlackWebhookHandler handler that allows you to specify an url for sending data.

// Laravel
LOG_CHANNEL=slack
LOG_SLACK_WEBHOOK_URL=http://127.0.0.1:23517/slack

mail

The RayServer runs an SMTP server and can be used as an email testing tool.

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

Running without Docker

Install php extension — swoole
Clone the project code to the directory.
Run the composer install command.
Start the server.

php artisan server:start --host=127.0.0.1 --port=23517
php artisan smtp:start --host=127.0.0.1 --port=1025

Enjoy!

Thanks for reading!

I hope you will love my humble but beloved RayServer. All information about it can be found at the links below:

Github project repository — https://github.com/butschster/debugger
Docker hub — https://hub.docker.com/repository/docker/butschster/debugger
You can leave your suggestions here

Follow me on Twitter: https://twitter.com/ButscH
Translator — Sasha B.
Copywriter — Olga T.