From c06bcb71191c15a34f1798cc226ae699cac0b117 Mon Sep 17 00:00:00 2001 From: Sebastian Schlein Date: Fri, 11 Jun 2021 16:09:40 +0200 Subject: [PATCH] Improve docs --- docs/client/basic-authentication.md | 4 ++-- docs/client/dashboard.md | 14 ++++++------- docs/client/sharing.md | 9 ++++----- docs/getting-started/installation.md | 13 ++++++------ docs/getting-started/questions-issues.md | 4 ++-- .../sharing-your-first-site.md | 20 +++++++++---------- docs/introduction.md | 13 ++++++------ 7 files changed, 37 insertions(+), 40 deletions(-) diff --git a/docs/client/basic-authentication.md b/docs/client/basic-authentication.md index 71aaa6f..6271f3a 100644 --- a/docs/client/basic-authentication.md +++ b/docs/client/basic-authentication.md @@ -7,7 +7,7 @@ order: 2 Expose allows you to share your local sites with custom basic authentication credentials. -This can be useful, if you have a static subdomain that you share with someone else, for example a client, and you want to provide some additional security to it. Before someone can access your shared site, they need to provide the correct credentials. +This is useful, if you have a static subdomain that you share with someone else, for example a client, and you want to provide some additional security to it. Before someone can access your shared site, they need to provide the correct credentials. > **Warning**: You can not add basic authentication to a website that already uses basic authentication. @@ -29,4 +29,4 @@ You can also use the basic authentication parameter in addition to a custom subd ```bash expose share my-site.test --subdomain=site --auth="admin:secret" -``` \ No newline at end of file +``` diff --git a/docs/client/dashboard.md b/docs/client/dashboard.md index 9bed808..9bb23be 100644 --- a/docs/client/dashboard.md +++ b/docs/client/dashboard.md @@ -5,19 +5,19 @@ order: 5 # Dashboard -Once you share a local site, expose will show you all incoming HTTP requests along with their status code and duration in your terminal: +Once you share a local site, Expose shows you all incoming HTTP requests along with their status code and duration in your terminal: ![](/img/expose_terminal.png) -While this is great to get a quick look of the incoming requests, you sometimes need more information than this. +While this is great to get a quick look of the incoming requests, you often need more information than this. -Because of that, expose is also exposing a web based dashboard on port 4040. +Because of that, Expose is also exposing a web based dashboard on port 4040. -Once you start sharing a site, expose will show you a QR code that you can scan with your mobile device, to easily browse your shared sites on your phone or tablet. +Once you start sharing a site, Expose shows you a QR code that you can scan with your mobile device, to easily browse your shared sites on your phone or tablet. ![](/img/expose_qr.png) -Once a request comes in, you can see all incoming HTTP requests as they hit your local site in realtime. -When you click on a specific request, you can see detailed information about the request and response. +When a request comes in, you can see all incoming HTTP requests as they hit your local site in realtime. +You can click on a specific request and see detailed information about the request and response. Expose provides several tools for developers to make webhook testing easier – the most powerful one is that you can replay requests without firing the webhook again. So if your previous process required to create multiple test orders to see how the paylods of your payment provider look like, Expose makes this a breeze by allowing you to replay these requests without creating more orders. -![](/img/expose_dashboard_details.png) \ No newline at end of file +![](/img/expose_dashboard_details.png) diff --git a/docs/client/sharing.md b/docs/client/sharing.md index d1871f2..f0142c4 100644 --- a/docs/client/sharing.md +++ b/docs/client/sharing.md @@ -7,11 +7,11 @@ order: 1 Expose allows you to share any kind of HTTP/HTTPS traffic for websites that you can reach on your own computer, with anyone on the internet. -There are multiple different ways on how you can initiate the site sharing with Expose. +There are multiple ways to share a site with Expose. ## Sharing the current working directory -To share the current working directory with expose, all you need to do is go into the directory and call `expose`. +To share the current working directory with Expose, all you need to do is go into the directory and call `expose`. This makes the assumption that you have access to the current working directory name as a domain with the `.test` TLD. @@ -48,8 +48,7 @@ expose share https://my-local-site.dev ## Share a local site with a given subdomain -You can also share one of your local sites explicitly and specify which exact subdomain you want Expose to use when sharing the site. -This works similar to the paid offerings of Ngrok - but you can use it with your own custom server. +You can also share one of your local sites explicitly and specify the exact subdomain that you want to use when sharing the site. This is very useful if you are testing webhooks and want to use the same webhook configuration and don't update the webhook endpoints on every Expose connect. Custom subdomains require an own Expose server in your infrastructure or Expose Pro. To specify the subdomain, pass the `--subdomain` option to expose: @@ -57,4 +56,4 @@ To specify the subdomain, pass the `--subdomain` option to expose: expose share my-site.test --subdomain=my-site ``` -If the chosen subdomain is already taken on the Expose server, you will see an error message and the connection to the Expose server gets closed. +If someone already uses the chosen subdomain on the Expose server, you will see an error message and the Expose server closes the connection. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index b8aec1b..dd5cd21 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -4,20 +4,19 @@ order: 1 --- # Installation - -Expose can be installed using composer. -The easiest way to install expose is by making it a global composer dependency: + +Expose is a PHP package and you can install the client for your local machine as a global composer dependency: ```bash composer global require beyondcode/expose ``` -Now you're ready to go and can [share your first site](/docs/expose/getting-started/sharing-your-first-site). +After that, you are ready to go and can [share your first site](/docs/expose/getting-started/sharing-your-first-site). ### Extending Expose -By default, expose comes as an executable PHAR file. This allows you to use all of the expose features, like sharing your local sites, out of the box - without any additional setup required. +By default, Expose comes as an executable PHAR file. This allows you to use all Expose features out of the box – without any additional setup required. -If you want to modify expose, for example by adding custom request/response modifiers, you will need to clone the GitHub repository instead. +If you want to modify Expose and want to add custom request/response modifiers, you need to clone the GitHub repository instead of the global composer dependency. -You can learn more about how to customize expose in the [extending Expose](/docs/expose/extending-the-server/subdomain-generator) documentation section. +You can learn more about the customization of Expose in the [extending Expose](/docs/expose/extending-the-server/subdomain-generator) documentation section. diff --git a/docs/getting-started/questions-issues.md b/docs/getting-started/questions-issues.md index 267873b..55ee5c9 100644 --- a/docs/getting-started/questions-issues.md +++ b/docs/getting-started/questions-issues.md @@ -5,6 +5,6 @@ order: 3 # Questions and issues -Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving expose? Feel free to create an issue on [GitHub](https://github.com/beyondcode/expose/issues), we'll try to address it as soon as possible. +Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving Expose? Feel free to create an issue on [GitHub](https://github.com/beyondcode/expose/issues), we'll try to address it as soon as possible. -If you've found a bug regarding security please mail [marcel@beyondco.de](mailto:marcel@beyondco.de) instead of using the issue tracker. \ No newline at end of file +If you've found a bug regarding security please mail [marcel@beyondco.de](mailto:marcel@beyondco.de) instead of using the issue tracker. diff --git a/docs/getting-started/sharing-your-first-site.md b/docs/getting-started/sharing-your-first-site.md index 32e6764..bca19e1 100644 --- a/docs/getting-started/sharing-your-first-site.md +++ b/docs/getting-started/sharing-your-first-site.md @@ -5,9 +5,9 @@ order: 2 # Share your first site -Once you have installed Expose, you are ready to go and share your local sites. +Once you have installed Expose, you are ready to go and share your first local site. -The easiest way to share your local sites is by going into the folder that you want to share and run `expose`: +The easiest way to share your local sites is by going into the folder that you want to share and run the `expose` command from your command line: ```bash cd ~/Sites/my-awesome-project/ @@ -15,19 +15,17 @@ cd ~/Sites/my-awesome-project/ expose ``` -This will connect to the provided server at sharedwithexpose.com and give you a tunnel that you can immediately start using. +This command uses your Expose network token and connects to the Expose network server at sharedwithexpose.com and creates a tunnel. If you don't have an Expose token and don't want to host your own server, you can create a free account and get a token [here](https://beyondco.de/login). -To learn more about how you can share your local sites, check out the [sharing local sites](/docs/expose/client/sharing) documentation. +To learn more about sharing your local sites, check out the [sharing local sites](/docs/expose/client/sharing) documentation. -## Using the provided server at sharedwithexpose.com +## Using the Expose network at sharedwithexpose.com -A big advantage of Expose over other alternatives such as ngrok, is the ability to host your own server. To make sharing your sites as easy as possible, we provide and host a custom expose server on our own - so getting started with expose is a breeze. +Expose is the only open source tunnel service that is written in PHP. This means that you can host your own server and this on its own makes it a fantastic alternative to ngrok. -This server is available free of charge for everyone, but makes use of Expose's authentication token authorization method. +Before you install your own server, you can try Expose with the free plan of the Expose network and see if your like the features for PHP developers. To access the Expose network, you need an Expose token. -Therefore, in order to share your sites for the first time, you will need an authorization token. - -You can obtain such a token by signing in to your [Beyond Code account](https://beyondco.de/login). If you do not yet have an account, you can [sign up and create an account](https://beyondco.de/register) for free. +You can obtain a token by signing in to your [Beyond Code account](https://beyondco.de/login). If you don't have an account, you can [sign up and create an account](https://beyondco.de/register) for free. ## Authenticating with sharedwithexpose.com @@ -37,4 +35,4 @@ To register and use the given credentials, just run the following command: expose token [YOUR-AUTH-TOKEN] ``` -This will register the token globally in your expose configuration file, and all following expose calls will automatically use the token to authenticate with the server. +This will register the token globally in your expose configuration file and all following Expose calls will automatically use the token to authenticate with the network. In case that you have access to a team on an Expose Pro plan, you can use this command to switch to the team and get access to the reserved subdomains or white label domains. diff --git a/docs/introduction.md b/docs/introduction.md index b6e3139..e3fdddc 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -5,15 +5,16 @@ order: 1 # Introduction -Expose is a beautiful, open source, tunnel application that allows you to share your local websites with others via the internet. +Expose is an open source tunnel application that allows you to share your local sites and applications with others on the internet. -Since you can host the server yourself, you have full control over the domains that your shared sites will be available at. -You can extend expose with additional features and middleware classes on the server and client side, to make it suit your specific needs. +You can host your own Expose server and customize the application to your own needs or create a [free Beyond Code Account](https://beyondco.de/login) and use our managed infrastructure. The managed Expose network has a free plan that uses the test infrastrcture in our data center in Germany – and a Pro plan that uses the global Expose network with access points in all over the world. -Expose comes with a beautiful CLI view and web-based dashboard that show you incoming HTTP requests on the client. +If you decide to host your own server, you can extend Expose with additional features and middleware classes on the server and client side. This gives your the full flexibility of true customization but comes with some maintenance overhead. -Expose serves as an alternative to ngrok. +Expose itself comes with a beautiful CLI view and a web-based dashboard that show you incoming HTTP requests on the client. + +Expose is the alternative to ngrok for PHP developers. ![](/img/expose_terminal.png) -![](/img/expose_dashboard_details.png) \ No newline at end of file +![](/img/expose_dashboard_details.png)