bitinflow/expose
1
0
Fork 0
mirror of https://github.com/bitinflow/expose.git synced 2026-03-13 13:35:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

wip

Browse Source
This commit is contained in:
Marcel Pociot
2020-06-04 21:41:31 +02:00
parent df4005482c
commit f3d2b088da
26 changed files with 537 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/api/authentication.md
View File

@@ -1,8 +0,0 @@
---
title: Basic Authentication
order: 8
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

9
docs/api/authorization.md Normal file
View File

@@ -0,0 +1,9 @@
---
title: Authorization
order: 1
---
# Authorization
The Expose server API uses the same authentication method as the expose admin interface itself.
So you can use any of the configured user/password combinations as basic authentication.

8
docs/api/configuration.md
View File

@@ -1,8 +0,0 @@
---
title: Configuration
order: 1
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/api/dashboard.md
View File

@@ -1,8 +0,0 @@
---
title: Dashboard
order: 5
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/api/extending.md
View File

@@ -1,8 +0,0 @@
---
title: Extending
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

56
docs/api/settings.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: Settings
order: 2
---
# Settings
Expose provides two API endpoints that allow you to either read or update the currently active server settings.
## Reading the settings
To retrieve the currently active configuration, you can perform a GET request to the `/api/settings` endpoint:
The result looks like this:
```json
{
"configuration":{
"hostname": "expose.dev",
"port": 8080,
"database": "/home/forge/expose/database/expose.db",
"validate_auth_tokens": false,
"maximum_connection_length": 0,
"subdomain": "expose",
"subdomain_generator": "App\\Server\\SubdomainGenerator\\RandomSubdomainGenerator",
"users": {
"username":"password"
},
"user_repository": "App\\Server\\UserRepository\\DatabaseUserRepository",
"messages": {
"message_of_the_day":"Thank you for using expose.",
"invalid_auth_token":"Authentication failed. Please check your authentication token and try again.",
"subdomain_taken":"The chosen subdomain :subdomain is already taken. Please choose a different subdomain."
}
}
}
```
## Updating the settings
To update the currently active settings, send a POST requests to the `/api/settings` endpoint.
The endpoint expects you to send the following data:
```
validate_auth_tokens: BOOLEAN
maximum_connection_length: INTEGER
messages: ARRAY
messages.message_of_the_day: STRING
messages.invalid_auth_token: STRING
messages.subdomain_taken: STRING
```
You will receive a response containing the updated configuration as JSON.

8
docs/api/sharing.md
View File

@@ -1,8 +0,0 @@
---
title: Sharing your local sites
order: 1
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

32
docs/api/sites.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: Sites
order: 3
---
# Sites
Expose provides two API endpoints that allow you to either retrieve all currently shared sites, or disconnect a site with a given site ID.
## Retrieving all shared sites
To retrieve the currently shared sites, you can perform a GET request to the `/api/sites` endpoint:
The result looks like this:
```json
{
"sites":[
{
"id":10,
"host":"beyondco.de.test",
"client_id":"5ed94b485e2f6",
"subdomain":"beyondcode",
"shared_at":"2020-06-04 19:28:08"
}
]
}
```
## Disconnecting a shared site
To disconnect a shared site from your server, you can perform a DELETE request to the `/api/sites/{site_id}` endpoint.

72
docs/api/users.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Users
order: 4
---
# Users
Expose provides three API endpoints that allow you to either retrieve all registered users, create a new user, or delete an existing user from the expose server.
## Retrieving all users
To retrieve the users, you can perform a GET request to the `/api/users` endpoint:
The result looks like this:
```json
{
"users":[
{
"id":9,
"name":"miguel",
"auth_token":"858fad3d-2163-4af6-8c8d-68e89f80cf8c",
"created_at":"2020-06-04 19:31:26",
"updated_at":null
},
{
"id":8,
"name":"sebastian",
"auth_token":"360461ea-23b9-422e-bc76-7ca1b2ec8a91",
"created_at":"2020-06-04 19:31:17",
"updated_at":null
},
{
"id":7,
"name":"marcel",
"auth_token":"b5f3ee57-1e77-4a94-8b7f-da13e3dc6478",
"created_at":"2020-06-04 19:31:16",
"updated_at":null
}
]
}
```
## Creating a new user
To create a new user on the expose server, you can perform a POST request to the `/api/users` endpoint.
The endpoint expects you to send the following data:
```json
name: STRING
```
This will return a response containing the generated user:
```json
{
"user": {
"id":8,
"name":"sebastian",
"auth_token":"360461ea-23b9-422e-bc76-7ca1b2ec8a91",
"created_at":"2020-06-04 19:31:17",
"updated_at":null
}
}
```
## Deleting a user
To delete a user on the expose server, you can perform a DELETE request to the `/api/users/{user_id}` endpoint.
> **Note:** The users currently active shared sites will not be disconnected automatically.

12
docs/client/dashboard.md
View File

@@ -9,3 +9,15 @@ Once you share a local site, expose will show you all incoming HTTP requests alo
![](/img/expose_terminal.png)
While this is great to get a quick look of the incoming requests, you sometimes need more information than this.
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.
![](/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.
![](/img/expose_dashboard_details.png)

8
docs/client/extending.md
View File

@@ -1,8 +0,0 @@
---
title: Extending
order: 100
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

4
docs/extending-the-server/_index.md Normal file
View File

@@ -0,0 +1,4 @@
---
title: Extending The Server
order: 5
---

43
docs/extending-the-server/subdomain-generator.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: Subdomain Generator
order: 1
---
# Subdomain Generator
When a user does not explicitly specify a custom subdomain, the expose server takes care of generating a random unique subdomain.
The default generator looks like this:
```php
use Illuminate\Support\Str;
use App\Contracts\SubdomainGenerator;
class RandomSubdomainGenerator implements SubdomainGenerator
{
public function generateSubdomain(): string
{
return strtolower(Str::random(10));
}
}
```
It simply generates a random lowercase string.
You can create your own custom subdomain generator class, by implementing the `SubdomainGenerator` interface.
Next you need to specify your custom subdomain generator in your expose configuration file:
```php
/*
|--------------------------------------------------------------------------
| Subdomain Generator
|--------------------------------------------------------------------------
|
| This is the subdomain generator that will be used, when no specific
| subdomain was provided. The default implementation simply generates
| a random string for you. Feel free to change this.
|
*/
'subdomain_generator' => \App\Server\SubdomainGenerator\RandomSubdomainGenerator::class,
```

29
docs/extending-the-server/user-repository.md Normal file
View File

@@ -0,0 +1,29 @@
---
title: User Repository
order: 2
---
# User Repository
The expose server tries to load users out of the built-in SQLite database by default.
If you want to change the default implementation and load your users from a different storage engine, you can implement the `UserRepository` interface and change it in your expose configuration file.
This is how the interface looks like:
```php
use React\Promise\PromiseInterface;
interface UserRepository
{
public function getUsers(): PromiseInterface;
public function getUserById($id): PromiseInterface;
public function getUserByToken(string $authToken): PromiseInterface;
public function storeUser(array $data): PromiseInterface;
public function deleteUser($id): PromiseInterface;
}
```

5
docs/introduction.md
View File

@@ -6,11 +6,14 @@ order: 1
# Introduction
Expose is a beautiful, open source, tunnel application that allows you to share your local websites with others via 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.
Expose comes with a beautiful CLI view and web-based dashboard that show you incoming HTTP requests on the client.
Expose serves as an alternative to ngrok.
![](/img/expose_terminal.png)
![](/img/dashboard.png)
![](/img/expose_dashboard_details.png)

81
docs/server/admin-interface.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Admin Interface
order: 3
---
# Admin Interface
The Expose server comes with a beautiful admin interface, that makes configuring your server a breeze.
The admin interface is available at a specific subdomain on your expose server. By default it is called "expose", but you can change this in the configuration file:
```
...
/*
|--------------------------------------------------------------------------
| Subdomain
|--------------------------------------------------------------------------
|
| This is the subdomain that your expose admin dashboard will be available at.
| The given subdomain will be reserved, so no other tunnel connection can
| request this subdomain for their own connection.
|
*/
'subdomain' => 'expose',
...
```
So you can reach the admin interface at http://expose.your-domaion.com.
## Authentication
Since the expose admin interface allows you to change and modify your expose server configuration at runtime, access to the admin interface is protected using basic authentication.
You can define which user/password combinations are allowed in the configuration file:
> **Note:** You will need to restart your expose server, once you change this setting in order for the changes to take effect.
```
...
/*
|--------------------------------------------------------------------------
| Users
|--------------------------------------------------------------------------
|
| The admin dashboard of expose is protected via HTTP basic authentication
| Here you may add the user/password combinations that you want to
| accept as valid logins for the dashboard.
|
*/
'users' => [
'username' => 'password'
],
...
```
### Users
![](/img/expose_users.png)
Here you can list, add and delete all users that you want to be able to connect to your expose server.
The users will be stored in a SQLite database that can be modified in the expose configuration file.
You only need to add users to your expose server, if you have the auth token validation enabled.
### Shared sites
![](/img/expose_admin.png)
Once you and others start sharing their local sites with your server, you can see a list of all connectes sites here.
You can see the original client host that was shared, the subdomain that was associated to this and the time and date the site was shared.
The expose server can also disconnect a site from the server. Just press on the "Disconnect" button and the client connection will be closed.
### Settings
![](/img/expose_settings.png)
Here you can see and modify your Expose server settings.

8
docs/server/administrators.md
View File

@@ -1,8 +0,0 @@
---
title: Administrators
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/server/configuration.md
View File

@@ -1,8 +0,0 @@
---
title: Configuration
order: 1
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/server/connection_length.md
View File

@@ -1,8 +0,0 @@
---
title: Maximum connection length
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/server/extending.md
View File

@@ -1,8 +0,0 @@
---
title: Extending
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/server/motd.md
View File

@@ -1,8 +0,0 @@
---
title: Message of the day
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

34
docs/server/server-configuration.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: Server Configuration
order: 5
---
# Server Configuration
Within the Expose admin interface, you can configure how you want your specific expose server to behave.
Here are the available settings:
![](/img/expose_settings.png)
## Authentication
When you start your expose server, anyone is able to connect to it by default. If you want to restrict your server only to users that have a valid "authentication token", you can simply check the checkbox. Only registered users / authentication tokens are then able to connect to your server.
> **Note:** This is only a temporary modification for as long as your expose server is running. To permanently enable this feature, modify your expose config file.
## Message of the day
This message will be shown when a sucessful connection to the expose server can be established. You can change it on demand, or modify it permanently in your expose configuration file.
## Maximum connection length
You can define how long you want your users connection to your expose server to be open at maximum. This time can be configured in minutes. Once the connection exceeds the specified duration, the client connection gets closed automatically.
## Authentication failed
This message will be shown when a user tries to connect with an invalid authentication token. If your users can somehow obtain an authentication token, this is a great place to let them know how to do it.
## Subdomain taken
This message will be shown when a user tries to connect with an already registered subdomain. This could be any user-registered subdomain, as well as the expose admin dashboard subdomain.

39
docs/server/ssl.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: SSL Support
order: 2
---
# SSL Support
Once your Expose server is running, you can onyl access it over the port that you configure when the server gets started.
If you want to enable SSL support, you will need to use a proxy service - like Nginx, HAProxy or Caddy - to handle the SSL configurations and proxy all requests in plain HTTP to your expose server.
A basic Nginx configuration would look like this, but you might want to tweak the SSL parameters to your liking.
```
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name expose.yourapp.tld;
# Start the SSL configurations
ssl on;
ssl_certificate /etc/letsencrypt/live/expose.yourapp.tld/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/expose.yourapp.tld/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_read_timeout 60;
proxy_connect_timeout 60;
proxy_redirect off;
# Allow the use of websockets
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
```

122
docs/server/starting-the-server.md Normal file
View File

@@ -0,0 +1,122 @@
---
title: Starting the server
order: 1
---
# Starting the server
You can host your own custom Expose server in order to make use of your own domain, when sharing your local sites.
The expose binary that you install via composer contains both the server and the client, so you do not need any additional software for this to work.
Once you have successfully downloaded expose, you can start the server using this command:
````bash
expose serve my-domain.com
````
This will start listening for incoming expose client connections on port 8080 by default.
If you want, you can customize the port:
```bash
expose serve my-domain.com --port=3000
```
## Validating auth tokens
When you start your expose server, anyone is able to connect to it by default. If you want to restrict your server only to users that have a valid "authentication token", you can start the server with the `--validateAuthTokens` option:
```bash
expose serve my-domain.com --validateAuthTokens
```
Don't worry - you can also changes this later on through the admin interface.
## Keeping the expose server running with supervisord
The `expose serve` daemon needs to always be running in order to accept connections. This is a prime use case for `supervisor`, a task runner on Linux.
First, make sure `supervisor` is installed.
```bash
# On Debian / Ubuntu
apt install supervisor
# On Red Hat / CentOS
yum install supervisor
systemctl enable supervisord
```
Once installed, add a new process that `supervisor` needs to keep running. You place your configurations in the `/etc/supervisor/conf.d` (Debian/Ubuntu) or `/etc/supervisord.d` (Red Hat/CentOS) directory.
Within that directory, create a new file called `expose.conf`.
```bash
[program:expose]
command=/usr/bin/php /home/expose/expose serve
numprocs=1
autostart=true
autorestart=true
user=forge
```
Once created, instruct `supervisor` to reload its configuration files (without impacting the already running `supervisor` jobs).
```bash
supervisorctl update
supervisorctl start expose
```
Your expose server should now be running (you can verify this with `supervisorctl status`). If it were to crash, `supervisor` will automatically restart it.
Please note that, by default, `supervisor` will force a maximum number of open files onto all the processes that it manages. This is configured by the `minfds` parameter in `supervisord.conf`.
If you want to increase the maximum number of open files, you may do so in `/etc/supervisor/supervisord.conf` (Debian/Ubuntu) or `/etc/supervisord.conf` (Red Hat/CentOS):
```
[supervisord]
minfds=10240; (min. avail startup file descriptors;default 1024)
```
After changing this setting, you'll need to restart the supervisor process (which in turn will restart all your processes that it manages).
## Connecting the client
To configure a client to connect to your custom server, first [publish the configuration file](/docs/expose/client/configuration) on the client. Once that is done, you can change the `host` and `port` configuration values on your client.
```php
return [
/*
|--------------------------------------------------------------------------
| Host
|--------------------------------------------------------------------------
|
| The expose server to connect to. By default, expose is using the free
| expose.dev server, offered by Beyond Code. You will need a free
| Beyond Code account in order to authenticate with the server.
| Feel free to host your own server and change this value.
|
*/
'host' => 'my-domain.com',
/*
|--------------------------------------------------------------------------
| Port
|--------------------------------------------------------------------------
|
| The port that expose will try to connect to. If you want to bypass
| firewalls and have proper SSL encrypted tunnels, make sure to use
| port 443 and use a reverse proxy for Expose.
|
| The free default server is already running on port 443.
|
*/
'port' => 3030,
// ...
```
Now that your basic expose server is running, let's take a look at how you can add SSL support.

8
docs/server/subdomain_generator.md
View File

@@ -1,8 +0,0 @@
---
title: Subdomain Generator
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.

8
docs/server/users.md
View File

@@ -1,8 +0,0 @@
---
title: User Repository
order: 10
---
# Sharing local sites
This page will be under the "Basic Usage" submenu.