diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index e1d5686..0062d75 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -20,26 +20,23 @@ export default defineConfig({ text: 'Getting Started', link: '/getting-started', }, + { - text: 'Contributing', + text: 'Trap', items: [ { - text: 'Architecture', - link: '/contributing/architecture', - }, - { - text: 'Server', - link: '/contributing/server', + text: 'What is Trap?', + link: '/trap/what-is-trap', }, { - text: 'Frontend', - link: '/contributing/frontend', - }, + text: 'Getting Started', + link: '/trap/getting-started', + } ] }, { - text: 'Configuration', + text: 'Integrations', items: [ {text: 'XHProf', link: '/config/xhprof'}, {text: 'VarDumper', link: '/config/var-dumper'}, @@ -50,7 +47,37 @@ export default defineConfig({ {text: 'Inspector', link: '/config/inspector'}, {text: 'Http Dumps', link: '/config/http-dumps'}, ] - } + }, + + { + text: 'Configuration', + items: [ + {text: 'Single Sign On (SSO)', link: '/config/sso'}, + {text: 'External Database', link: '/config/external-db'}, + ] + }, + + { + text: 'Contributing', + items: [ + { + text: 'Getting Started', + link: '/contributing', + }, + { + text: 'Architecture', + link: '/contributing/architecture', + }, + { + text: 'Server', + link: '/contributing/server', + }, + { + text: 'Frontend', + link: '/contributing/frontend', + }, + ] + }, ], socialLinks: [ diff --git a/docs/config/external-db.md b/docs/config/external-db.md new file mode 100644 index 0000000..6ca4174 --- /dev/null +++ b/docs/config/external-db.md @@ -0,0 +1,87 @@ +# Configuration — External Database + +Buggregator supports the configuration of external databases for storing events, allows for greater flexibility and +scalability in handling event data. + +## Configuration Overview + +Events in Buggregator are traditionally stored in local in-memory storage by default. After release 1.7.0, users can +opt to store events in external databases like **MongoDB** or **PostgreSQL**. This configuration is managed via +environment variables, enabling easy integration and setup. + +Buggregator supports the following databases: + +- PostgreSQL +- MongoDB + +To use an external database, set the `PERSISTENCE_DRIVER` environment variable to `database` for PostgreSQL or `mongodb` +for MongoDB. + +## PostgreSQL + +Provide the connection details specific to the type of database you are using. + +```dotenv +PERSISTENCE_DRIVER=database + +DB_DRIVER=pgsql +DB_DATABASE=buggregator +DB_HOST=127.0.0.1 +DB_PORT=5432 +DB_USERNAME=homestead +DB_PASSWORD=secret +``` + +### Ensuring the Database is Ready + +Before starting Buggregator, make sure that the database is already created and accessible as specified in your +environment settings. + +> **Warning**: Buggregator does not create the database itself; it only creates the tables within the existing +> database. + +### Running Migrations + +Buggregator automatically runs migrations when it starts. However, if you encounter any issues with the automatic +migrations, or if they were not executed for some reason, you can run them manually: + +1. **Connect to the Buggregator container:** + Depending on your setup, you might use Docker, Kubernetes, or any other container service. Use the appropriate + command to access the shell of the running Buggregator container. + + For example, if you are using Docker, you can use the following command: + + ```bash + docker exec -it buggregator /bin/bash + ``` + + Replace `buggregator` with the name of your Buggregator container. + + If you are using Kubernetes, you can use the following command: + + ```bash + kubectl exec -it buggregator -- /bin/bash + ``` + + Replace `buggregator` with the name of your Buggregator pod. + + +2. **Run the migration command:** + Within the Buggregator container, execute the following command to force the migrations: + + ```bash + php app.php migrate --force + ``` + + This command forcefully runs the migrations regardless of the current state, ensuring that all necessary tables are + properly set up in the database. + +## MongoDB + +Provide the connection details specific to the type of database you are using. + +```dotenv +PERSISTENCE_DRIVER=mongodb +MONGODB_CONNECTION=mongodb://127.0.0.1:27017 +MONGODB_DATABASE=buggregator +``` \ No newline at end of file diff --git a/docs/config/http-dumps.md b/docs/config/http-dumps.md index f3e9c4e..7bcfe10 100644 --- a/docs/config/http-dumps.md +++ b/docs/config/http-dumps.md @@ -1,4 +1,4 @@ -# Configuration — HTTP dumps +# Integration — HTTP dumps It's an indispensable tool that simplifies the process of capturing, analyzing, and debugging HTTP requests in their applications. With the HTTP Requests Dump Server, developers can effortlessly capture all the relevant request data and diff --git a/docs/config/inspector.md b/docs/config/inspector.md index a26aa74..5c9b45c 100644 --- a/docs/config/inspector.md +++ b/docs/config/inspector.md @@ -1,4 +1,4 @@ -# Configuration — Inspector +# Integration — Inspector Buggregator is also compatible with Inspector reports, providing you with a lightweight alternative for local development. With it, you can easily configure your Inspector client URL to send data directly to the server, making it diff --git a/docs/config/monolog.md b/docs/config/monolog.md index 69ed420..c148fbd 100644 --- a/docs/config/monolog.md +++ b/docs/config/monolog.md @@ -1,4 +1,4 @@ -# Configuration — Monolog +# Integration — Monolog Buggregator comes with a powerful Monolog server that can receive logs from the popular `monolog/monolog` package via the `\Monolog\Handler\SocketHandler` handler. With this feature, you can easily track and analyze the logs generated by diff --git a/docs/config/ray.md b/docs/config/ray.md index d7321b0..b6d2a63 100644 --- a/docs/config/ray.md +++ b/docs/config/ray.md @@ -1,4 +1,4 @@ -# Configuration — Spatie Ray +# Integration — Spatie Ray Buggregator is compatible with `spatie/ray` package. The Ray debug tool supports PHP, Ruby, JavaScript, TypeScript, NodeJS, Go and Bash applications. After installing one of the libraries, you can use the ray function to quickly dump diff --git a/docs/config/sentry.md b/docs/config/sentry.md index c9bb420..7c11442 100644 --- a/docs/config/sentry.md +++ b/docs/config/sentry.md @@ -1,4 +1,4 @@ -# Configuration — Sentry exceptions +# Integration — Sentry exceptions Buggregator offers seamless integration with Sentry reports, making it a reliable tool for local development. With it, you can easily configure your Sentry DSN to send data directly to the server, providing you with a lightweight diff --git a/docs/config/smtp.md b/docs/config/smtp.md index c968aaa..3cb98c0 100644 --- a/docs/config/smtp.md +++ b/docs/config/smtp.md @@ -1,4 +1,4 @@ -# Configuration — Fake SMTP server +# Integration — Fake SMTP server Buggregator is more than just a PHP debugging tool. It also includes a powerful email testing feature that allows you to install and configure a local email server with ease. diff --git a/docs/config/sso.md b/docs/config/sso.md new file mode 100644 index 0000000..7a81d77 --- /dev/null +++ b/docs/config/sso.md @@ -0,0 +1,71 @@ +# Configuration — Single Sign-On (SSO) + +With the release of version 1.7.0, Buggregator now supports Single Sign-On (SSO) using [Auth0](https://auth0.com/). This +integration allows users to authenticate with external identity providers supported by Auth0, providing a secure and +seamless sign-in experience. + +![image](https://github.com/buggregator/server/assets/773481/3bc5dd4b-b8ac-4e2c-a9c0-5707dd053d0b) + +By configuring SSO, you can streamline the authentication process and enhance the security of user management within +your application. + +## Prerequisites + +To configure SSO in Buggregator, you must have an [auth0.com](https://auth0.com/) account. If you do not have one, you +can sign up for free. + +## Configuration Steps + +To enable SSO, follow these steps: + +1. **Enable Authentication**: Set the environment variable `AUTH_ENABLED` to `true` to enable authentication features in + your application. + +2. **Create an Auth0 Application**: Log in to your Auth0 account and create a new "Regular Web + Application". After creating the application, you will receive a `Domain`, `Client ID` and `Client Secret` that you + will need to use in the next steps. + +3. **Configure Auth0 Settings**: Set up the following environment variables with the appropriate values from your Auth0 + application: + + - `AUTH_PROVIDER_URL`: The URL of your app domain, e.g., `https://.auth0.com` + - `AUTH_CLIENT_ID`: The client ID provided by app. + - `AUTH_CLIENT_SECRET`: The client secret provided by app. + - `AUTH_CALLBACK_URL`: The callback URL that app will redirect to after authentication, + e.g., `http://buggregator.server/auth/sso/callback`. Where `buggregator.server` is the domain of your Buggregator + server. + - `AUTH_SCOPES`: The scopes for which permissions are granted, typically include `openid`, `email`, and `profile`. + +4. **Set Up Callback URL**: In your Auth0 application settings, configure the callback URL to point to + the `http://buggregator.server/auth/sso/callback` endpoint. Where `buggregator.server` is the domain of your + Buggregator server. + +Resultant environment variables should look like this: + +```dotenv +AUTH_ENABLED=true +AUTH_PROVIDER_URL=https://.auth0.com +AUTH_CLIENT_ID=xxx +AUTH_CLIENT_SECRET=xxx +AUTH_CALLBACK_URL=http://buggregator.server/auth/sso/callback +AUTH_SCOPES=openid,email,profile +``` + +### Verifying the Configuration + +After configuring the environment variables, start your Buggregator server. You should now see Login page with the +option to sign in using Auth0. If set up correctly, clicking this option will redirect you to the Auth0 authentication +page where users can enter their credentials. + +After successful authentication, users will be redirected back to the Buggregator application and logged in. And you +will see the user's profile information in the bottom left corner of the application. + +![image](https://github.com/buggregator/frontend/assets/773481/6f996c5e-f43a-4f5e-8da4-71f83110c7ba) + +### Troubleshooting + +If you encounter issues during the authentication process, ensure that: + +- All environment variables are correctly set without any typos. +- The callback URL in your Auth0 configuration matches the `AUTH_CALLBACK_URL` you specified. +- Your Auth0 account has access to the scopes specified in `AUTH_SCOPES`. \ No newline at end of file diff --git a/docs/config/var-dumper.md b/docs/config/var-dumper.md index 182e0cb..70346da 100644 --- a/docs/config/var-dumper.md +++ b/docs/config/var-dumper.md @@ -1,4 +1,4 @@ -# Configuration — Symfony VarDumper server +# Integration — Symfony VarDumper server Buggregator is fully compatible with the [Symfony VarDumper](https://symfony.com/doc/current/components/var_dumper.html#the-dump-server) component. This is a diff --git a/docs/config/xhprof.md b/docs/config/xhprof.md index 598a9bf..8a9ff33 100644 --- a/docs/config/xhprof.md +++ b/docs/config/xhprof.md @@ -1,4 +1,4 @@ -# Configuration — Xhprof profiler +# Integration — Xhprof profiler The Xhprof profiler is an essential feature of Buggregator that offers a lightweight and hierarchical profiling solution for PHP applications. It uses instrumentation to keep track of call counts and inclusive metrics for arcs in the dynamic diff --git a/docs/contributing/server.md b/docs/contributing/server.md index 6b95fc9..0202c7b 100644 --- a/docs/contributing/server.md +++ b/docs/contributing/server.md @@ -19,7 +19,7 @@ Centrifugo. ## Server requirements -1. PHP 8.1 +1. Minimum PHP version: 8.2 ## Installation diff --git a/docs/index.md b/docs/index.md index 9b3b86e..53b313d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,11 @@ # What is Buggregator? -Buggregator is a free, multi-purpose server tool designed primarily for debugging PHP applications, but it's also -compatible with other programming languages. Think of it as a Swiss Army knife for developers. What makes it special is -that it offers a range of features that you would usually find in various paid tools, but it's available for free. +[Buggregator](https://github.com/buggregator/server) is a free, multi-purpose server tool designed primarily for +debugging PHP applications, but it's also compatible with other programming languages. Think of it as a Swiss Army knife +for developers. What makes it special is that it offers a range of features that you would usually find in various paid +tools, but it's available for free. + +**Project repository:** https://github.com/buggregator/server ![Cover image](https://github.com/buggregator/server/assets/773481/47491a3c-57a3-4b40-b82e-37976afdf708) @@ -13,9 +16,13 @@ The key feature of Buggregator is its ability to bring together debugging inform means you can see all your debugging data in one place, which makes fixing bugs a whole lot easier and faster. It's a great tool for any developer looking to streamline their debugging process without spending a lot of money. -## Centralized Debugging with Buggregator +If you don't have Docker or you need debug your local PHP application, you can +use [Buggregator Trap](./trap/what-is-trap.md). It's a lightweight alternative to the full Buggregator server, designed +for local debugging. + +## What makes it special? -1. **Unified Debugging Dashboard**: Buggregator allows you to aggregate logs, dumps, and other debug information from +1. **Unified Debugging Dashboard**: It allows you to aggregate logs, dumps, and other debug information from all your services into a single, unified interface. This centralization of data is invaluable for developers who manage multiple services or microservices, as it simplifies tracking and analysis. @@ -28,6 +35,20 @@ great tool for any developer looking to streamline their debugging process witho 4. **Ease of Access and Use**: By integrating Buggregator into your Docker development infrastructure, you set up a system where all debug information is automatically sent to Buggregator's server. +5. **Kubernetes Compatibility**: Deploy Buggregator in your Kubernetes cluster to enhance debugging and operational + efficiency. + +6. **SSO support**: Securely manage user access and authentication through Single Sign-On (SSO) with providers like + [Auth0](https://auth0.com/). + +7. **External database support**: Configure Buggregator to use external databases like MongoDB or PostgreSQL for event + storage. This flexibility allows you to scale storage according to your project needs. + +8. **Full source code available**: Buggregator is open-source, so you can customize it to suit your requirements or + contribute to its development. + +9. **Free to use**: Buggregator is free to use, making it an accessible and cost-effective solution for developers. + ## Tech stack It's built on a foundation of robust and reliable technologies, including the Spiral Framework, NuxtJs 3, and @@ -105,4 +126,11 @@ You can share dumps with your colleagues or friends. Just click on the share but Buggregator is designed with simplicity and efficiency in mind, requiring no additional packages for its operation. This makes it an accessible tool for developers at all levels, from beginners to seasoned professionals. Its Docker compatibility ensures it can be easily integrated into your existing development setup, enhancing your workflow without -adding complexity. \ No newline at end of file +adding complexity. + +## Contribute to Our Success + +Become a part of our community and help enhance Buggregator by contributing your skills. Whether you're fixing bugs, +adding features, or improving documentation, every contribution matters. + +Here you can find our [contribution guidelines](./contributing.md) \ No newline at end of file diff --git a/docs/trap/getting-started.md b/docs/trap/getting-started.md new file mode 100644 index 0000000..41634eb --- /dev/null +++ b/docs/trap/getting-started.md @@ -0,0 +1,95 @@ +# Trap — Getting Started + +To use Trap into your project, simply add it as a development dependency via Composer: + +```bash +composer require --dev buggregator/trap -W +``` + +After installation, you can start the debugging server using: + +```bash +vendor/bin/trap +``` + +This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will +see a convenient report about it right here in the terminal or in the browser. + +## Usage + +The Trap offers a flexible and straightforward way to capture and analyze debug information in your PHP applications. + +Below is a guide on how to use the `trap` function to send debug messages to the Trap server. + +#### Sending Debug Messages + +To begin sending debug messages, you can utilize the `trap()` function in various ways to suit your debugging needs: + +```php +// Dump the current stack trace +trap()->stackTrace(); + +// Dump a variable with a specific depth limit +trap($var)->depth(4); + +// Dump a sequence of named variables +trap($var, foo: $far, bar: $bar); + +// Dump a variable and return it for further processing +$responder->respond(trap($response)->return()); +``` + +> **Note:** When using `trap()`, it automatically configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` if +> they are not already set. This ensures that the debug information is accurately captured and displayed. + +## Default port + +By default, Trap operates on port `9912`. To change the default port, you can use the `-p` option when starting the +server: + +For example, to switch to port `8000`, you would use the following command: + +```bash +vendor/bin/trap -p 8000 +``` + +This command sets the Trap server to run on port `8000`. + +### Choosing Your Senders + +Trap supports multiple methods ("senders") for outputting the debug information, allowing you to choose where your debug +dumps are sent: + +- **Console**: Outputs dumps directly in the console. +- **Server**: Sends dumps to a remote Buggregator server for centralized management and review. +- **File**: Saves dumps to a file, useful for auditing or detailed offline analysis. + +By default, dumps are displayed in the console. However, you can configure multiple senders simultaneously to suit your +workflow and requirements. For example, to use the console, file, and server senders together: + +```shell +vendor/bin/trap -s console -s file -s server +``` + +This setup ensures that you can view debug information in real-time, save it for later review, and also send it to a +remote server for centralized monitoring. Using Trap enhances your ability to diagnose and resolve issues +quickly and efficiently, making it a valuable addition to your development toolkit. + +## User Interface + +Trap is set to enhance its usability by introducing a convenient new feature that allows users to launch the web +interface of the Buggregator Server directly. This feature is aimed at improving accessibility and simplifying the +debugging process. + +![trap-ui](https://github.com/buggregator/trap/assets/4152481/1ccc2c85-2f81-4b62-8ae7-49ee76380674) + +By adding the `--ui` flag when starting the Trap server, you can automatically raise the web interface. This allows for +a more intuitive and graphical interaction with your debug data. + +```bash +vendor/bin/trap --ui +``` + +This command will start the Trap server with the web interface enabled, facilitating direct access to the server's +dashboard through your web browser. This is particularly useful for developers who prefer a graphical interface over +command line interactions, providing a seamless experience without the need for Docker or additional setup. \ No newline at end of file diff --git a/docs/trap/what-is-trap.md b/docs/trap/what-is-trap.md new file mode 100644 index 0000000..98c9d0b --- /dev/null +++ b/docs/trap/what-is-trap.md @@ -0,0 +1,46 @@ +# Trap — What is it? + +[Buggregator Trap](https://github.com/buggregator/trap) is a lightweight, standalone debugging tool designed to be +integrated with PHP applications. It is distributed as a Composer package and includes a suite of utilities that +significantly enhance the debugging capabilities traditionally available in PHP environments. + +**Project repository:** https://github.com/buggregator/trap + +**We care about the quality of our products' codebase and strive to provide the best user experience. Trap has passed +the Proof of Concept stage and is now an important part of the Buggregator ecosystem. We have big plans for the +development of the entire ecosystem, and we would be delighted if you join us on this journey.** + +#### Key Features: + +- **Dashboard Interface:** It features the same user-friendly dashboard as the full Buggregator Server, allowing for + seamless monitoring and management of debug outputs directly from the web. + +- **Console Application:** Includes a mini-server written entirely in PHP, eliminating the need for Docker or other + container technology. This makes it easier to deploy and use in a variety of development environments. + +- **Multiple Handlers:** Buggregator Trap supports various handlers for debugging such as **Symfony VarDumper**, + **Monolog**,**Sentry**, **SMTP**, **HTTP dumps**, **Ray**, and more. This versatility allows developers to tailor the + debugging process to their specific needs and existing development stack. + +- **Protobuf Debugging:** Offers an improved way to work with Google Protocol Buffers (protobuf) by providing clearer + and more concise debugging outputs, making the process of working with complex data structures more manageable. + +## Console Application + +Here's a sneak peek into the console output you can expect with Trap: + +### Symfony/var-dumper (proto) + +![var-dumper](https://github.com/buggregator/trap/assets/4152481/f4c855f5-87c4-4534-b72d-5b19d1aae0b0)\ + +### Binary Data + +![Binary Data](https://github.com/buggregator/trap/assets/4152481/cd8788ed-b10c-4b9a-b2e2-baa8912ea38d) + +### SMTP Mail Trap + +![smtp](https://github.com/buggregator/trap/assets/4152481/b11c4a7f-072a-4e66-b11d-9bbd3177bfe2) + +### HTTP Dump + +![http-dump](https://github.com/buggregator/trap/assets/4152481/48201ce6-7756-4402-8954-76a27489b632) \ No newline at end of file