Merge pull request #13 from buggregator/feature/new-sections

Adds new sections
buggregator · Apr 16, 2024 · f1a04ed · f1a04ed
2 parents 2844d72 + 5424446
commit f1a04ed
Show file tree

Hide file tree

Showing 15 changed files with 381 additions and 27 deletions.
diff --git 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
@@ -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
+```
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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://<domain>.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://<domain>.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`.
diff --git 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
@@ -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
@@ -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
@@ -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.
+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)