Skip to content

Commit f1a04ed

Browse files
butschsterbutschster
authored
Merge pull request #13 from buggregator/feature/new-sections
Adds new sections
2 parents 2844d72 + 5424446 commit f1a04ed

File tree

15 files changed

+381
-27
lines changed

15 files changed

+381
-27
lines changed

‎docs/.vitepress/config.mts

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -20,26 +20,23 @@ export default defineConfig({
2020
text: 'Getting Started',
2121
link: '/getting-started',
2222
},
23+
2324
{
24-
text: 'Contributing',
25+
text: 'Trap',
2526
items: [
2627
{
27-
text: 'Architecture',
28-
link: '/contributing/architecture',
29-
},
30-
{
31-
text: 'Server',
32-
link: '/contributing/server',
28+
text: 'What is Trap?',
29+
link: '/trap/what-is-trap',
3330
},
3431
{
35-
text: 'Frontend',
36-
link: '/contributing/frontend',
37-
},
32+
text: 'Getting Started',
33+
link: '/trap/getting-started',
34+
}
3835
]
3936
},
4037

4138
{
42-
text: 'Configuration',
39+
text: 'Integrations',
4340
items: [
4441
{text: 'XHProf', link: '/config/xhprof'},
4542
{text: 'VarDumper', link: '/config/var-dumper'},
@@ -50,7 +47,37 @@ export default defineConfig({
5047
{text: 'Inspector', link: '/config/inspector'},
5148
{text: 'Http Dumps', link: '/config/http-dumps'},
5249
]
53-
}
50+
},
51+
52+
{
53+
text: 'Configuration',
54+
items: [
55+
{text: 'Single Sign On (SSO)', link: '/config/sso'},
56+
{text: 'External Database', link: '/config/external-db'},
57+
]
58+
},
59+
60+
{
61+
text: 'Contributing',
62+
items: [
63+
{
64+
text: 'Getting Started',
65+
link: '/contributing',
66+
},
67+
{
68+
text: 'Architecture',
69+
link: '/contributing/architecture',
70+
},
71+
{
72+
text: 'Server',
73+
link: '/contributing/server',
74+
},
75+
{
76+
text: 'Frontend',
77+
link: '/contributing/frontend',
78+
},
79+
]
80+
},
5481
],
5582

5683
socialLinks: [

‎docs/config/external-db.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Configuration — External Database
2+
3+
Buggregator supports the configuration of external databases for storing events, allows for greater flexibility and
4+
scalability in handling event data.
5+
6+
## Configuration Overview
7+
8+
Events in Buggregator are traditionally stored in local in-memory storage by default. After release 1.7.0, users can
9+
opt to store events in external databases like **MongoDB** or **PostgreSQL**. This configuration is managed via
10+
environment variables, enabling easy integration and setup.
11+
12+
Buggregator supports the following databases:
13+
14+
- PostgreSQL
15+
- MongoDB
16+
17+
To use an external database, set the `PERSISTENCE_DRIVER` environment variable to `database` for PostgreSQL or `mongodb`
18+
for MongoDB.
19+
20+
## PostgreSQL
21+
22+
Provide the connection details specific to the type of database you are using.
23+
24+
```dotenv
25+
PERSISTENCE_DRIVER=database
26+
27+
DB_DRIVER=pgsql
28+
DB_DATABASE=buggregator
29+
DB_HOST=127.0.0.1
30+
DB_PORT=5432
31+
DB_USERNAME=homestead
32+
DB_PASSWORD=secret
33+
```
34+
35+
### Ensuring the Database is Ready
36+
37+
Before starting Buggregator, make sure that the database is already created and accessible as specified in your
38+
environment settings.
39+
40+
> **Warning**: Buggregator does not create the database itself; it only creates the tables within the existing
41+
> database.
42+
43+
### Running Migrations
44+
45+
Buggregator automatically runs migrations when it starts. However, if you encounter any issues with the automatic
46+
migrations, or if they were not executed for some reason, you can run them manually:
47+
48+
1. **Connect to the Buggregator container:**
49+
Depending on your setup, you might use Docker, Kubernetes, or any other container service. Use the appropriate
50+
command to access the shell of the running Buggregator container.
51+
52+
For example, if you are using Docker, you can use the following command:
53+
54+
```bash
55+
docker exec -it buggregator /bin/bash
56+
```
57+
58+
Replace `buggregator` with the name of your Buggregator container.
59+
60+
If you are using Kubernetes, you can use the following command:
61+
62+
```bash
63+
kubectl exec -it buggregator -- /bin/bash
64+
```
65+
66+
Replace `buggregator` with the name of your Buggregator pod.
67+
68+
69+
2. **Run the migration command:**
70+
Within the Buggregator container, execute the following command to force the migrations:
71+
72+
```bash
73+
php app.php migrate --force
74+
```
75+
76+
This command forcefully runs the migrations regardless of the current state, ensuring that all necessary tables are
77+
properly set up in the database.
78+
79+
## MongoDB
80+
81+
Provide the connection details specific to the type of database you are using.
82+
83+
```dotenv
84+
PERSISTENCE_DRIVER=mongodb
85+
MONGODB_CONNECTION=mongodb://127.0.0.1:27017
86+
MONGODB_DATABASE=buggregator
87+
```

‎docs/config/http-dumps.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — HTTP dumps
1+
# Integration — HTTP dumps
22

33
It's an indispensable tool that simplifies the process of capturing, analyzing, and debugging HTTP requests in their
44
applications. With the HTTP Requests Dump Server, developers can effortlessly capture all the relevant request data and

‎docs/config/inspector.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Inspector
1+
# Integration — Inspector
22

33
Buggregator is also compatible with Inspector reports, providing you with a lightweight alternative for local
44
development. With it, you can easily configure your Inspector client URL to send data directly to the server, making it

‎docs/config/monolog.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Monolog
1+
# Integration — Monolog
22

33
Buggregator comes with a powerful Monolog server that can receive logs from the popular `monolog/monolog` package via
44
the `\Monolog\Handler\SocketHandler` handler. With this feature, you can easily track and analyze the logs generated by

‎docs/config/ray.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Spatie Ray
1+
# Integration — Spatie Ray
22

33
Buggregator is compatible with `spatie/ray` package. The Ray debug tool supports PHP, Ruby, JavaScript, TypeScript,
44
NodeJS, Go and Bash applications. After installing one of the libraries, you can use the ray function to quickly dump

‎docs/config/sentry.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Sentry exceptions
1+
# Integration — Sentry exceptions
22

33
Buggregator offers seamless integration with Sentry reports, making it a reliable tool for local development. With
44
it, you can easily configure your Sentry DSN to send data directly to the server, providing you with a lightweight

‎docs/config/smtp.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Fake SMTP server
1+
# Integration — Fake SMTP server
22

33
Buggregator is more than just a PHP debugging tool. It also includes a powerful email testing feature that allows you to
44
install and configure a local email server with ease.

‎docs/config/sso.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Configuration — Single Sign-On (SSO)
2+
3+
With the release of version 1.7.0, Buggregator now supports Single Sign-On (SSO) using [Auth0](https://auth0.com/). This
4+
integration allows users to authenticate with external identity providers supported by Auth0, providing a secure and
5+
seamless sign-in experience.
6+
7+
![image](https://github.com/buggregator/server/assets/773481/3bc5dd4b-b8ac-4e2c-a9c0-5707dd053d0b)
8+
9+
By configuring SSO, you can streamline the authentication process and enhance the security of user management within
10+
your application.
11+
12+
## Prerequisites
13+
14+
To configure SSO in Buggregator, you must have an [auth0.com](https://auth0.com/) account. If you do not have one, you
15+
can sign up for free.
16+
17+
## Configuration Steps
18+
19+
To enable SSO, follow these steps:
20+
21+
1. **Enable Authentication**: Set the environment variable `AUTH_ENABLED` to `true` to enable authentication features in
22+
your application.
23+
24+
2. **Create an Auth0 Application**: Log in to your Auth0 account and create a new "Regular Web
25+
Application". After creating the application, you will receive a `Domain`, `Client ID` and `Client Secret` that you
26+
will need to use in the next steps.
27+
28+
3. **Configure Auth0 Settings**: Set up the following environment variables with the appropriate values from your Auth0
29+
application:
30+
31+
- `AUTH_PROVIDER_URL`: The URL of your app domain, e.g., `https://<domain>.auth0.com`
32+
- `AUTH_CLIENT_ID`: The client ID provided by app.
33+
- `AUTH_CLIENT_SECRET`: The client secret provided by app.
34+
- `AUTH_CALLBACK_URL`: The callback URL that app will redirect to after authentication,
35+
e.g., `http://buggregator.server/auth/sso/callback`. Where `buggregator.server` is the domain of your Buggregator
36+
server.
37+
- `AUTH_SCOPES`: The scopes for which permissions are granted, typically include `openid`, `email`, and `profile`.
38+
39+
4. **Set Up Callback URL**: In your Auth0 application settings, configure the callback URL to point to
40+
the `http://buggregator.server/auth/sso/callback` endpoint. Where `buggregator.server` is the domain of your
41+
Buggregator server.
42+
43+
Resultant environment variables should look like this:
44+
45+
```dotenv
46+
AUTH_ENABLED=true
47+
AUTH_PROVIDER_URL=https://<domain>.auth0.com
48+
AUTH_CLIENT_ID=xxx
49+
AUTH_CLIENT_SECRET=xxx
50+
AUTH_CALLBACK_URL=http://buggregator.server/auth/sso/callback
51+
AUTH_SCOPES=openid,email,profile
52+
```
53+
54+
### Verifying the Configuration
55+
56+
After configuring the environment variables, start your Buggregator server. You should now see Login page with the
57+
option to sign in using Auth0. If set up correctly, clicking this option will redirect you to the Auth0 authentication
58+
page where users can enter their credentials.
59+
60+
After successful authentication, users will be redirected back to the Buggregator application and logged in. And you
61+
will see the user's profile information in the bottom left corner of the application.
62+
63+
![image](https://github.com/buggregator/frontend/assets/773481/6f996c5e-f43a-4f5e-8da4-71f83110c7ba)
64+
65+
### Troubleshooting
66+
67+
If you encounter issues during the authentication process, ensure that:
68+
69+
- All environment variables are correctly set without any typos.
70+
- The callback URL in your Auth0 configuration matches the `AUTH_CALLBACK_URL` you specified.
71+
- Your Auth0 account has access to the scopes specified in `AUTH_SCOPES`.

‎docs/config/var-dumper.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Configuration — Symfony VarDumper server
1+
# Integration — Symfony VarDumper server
22

33
Buggregator is fully compatible with
44
the [Symfony VarDumper](https://symfony.com/doc/current/components/var_dumper.html#the-dump-server) component. This is a

0 commit comments

Comments
 (0)