|
1 | | -# ngrok |
| 1 | +<h1> <img src="https://user-images.githubusercontent.com/550861/222650471-a1908709-8920-406b-a55d-b8231cd3a4a5.svg" width="25"> Ngrok Docker Desktop Extension</h1> |
2 | 2 |
|
3 | | - |
| 3 | +Get your local Docker containers on the internet using [Ngrok](https://ngrok.com/) with this Docker Desktop extension. |
4 | 4 |
|
5 | | -This repository defines an example of a Docker extension. The files in this repository have been automatically generated as a result of running `docker extension init`. |
| 5 | +## Installation |
6 | 6 |
|
7 | | -This extension is composed of: |
| 7 | +To install the extension: |
8 | 8 |
|
9 | | -- A [frontend](./ui) app in React that makes a request to the `/hello` endpoint and displays the payload in Docker Desktop. |
10 | | -- A [backend](./backend) container that runs an API in Go. It exposes the `/hello` endpoint which returns a JSON payload. |
| 9 | +1. Open Docker Desktop and go to the extensions marketplace. |
| 10 | +2. Search for "Ngrok" and click "Install". |
| 11 | +3. Once installed, activate the extension by clicking on the Ngrok icon in the Docker Desktop toolbar. |
11 | 12 |
|
12 | | -> You can build your Docker Extension using your fav tech stack: |
13 | | -> |
14 | | -> - Frontend: React, Angular, Vue, Svelte, etc. |
15 | | -> Basically, any frontend framework which generates an index.html with CSS, and JS assets. |
16 | | -> - Backend (optional): anything that can run in a container. |
| 13 | +## Usage |
17 | 14 |
|
18 | | -<details> |
19 | | - <summary>Looking for more templates?</summary> |
| 15 | +To use the extension: |
20 | 16 |
|
21 | | -1. [React + NodeJS](https://github.com/benja-M-1/node-backend-extension). |
22 | | -2. [React + .NET 6 WebAPI](https://github.com/felipecruz91/dotnet-api-docker-extension). |
23 | | - |
24 | | -Request one or submit yours [here](https://github.com/docker/extensions-sdk/issues). |
25 | | - |
26 | | -</details> |
27 | | - |
28 | | -## Local development |
29 | | - |
30 | | -You can use `docker` to build, install and push your extension. Also, we provide an opinionated [Makefile](Makefile) that could be convenient for you. There isn't a strong preference of using one over the other, so just use the one you're most comfortable with. |
31 | | - |
32 | | -To build the extension, use `make build-extension` **or**: |
33 | | - |
34 | | -```shell |
35 | | - docker buildx build -t ngrok/ngrok-docker-extension:latest . --load |
36 | | -``` |
37 | | - |
38 | | -To install the extension, use `make install-extension` **or**: |
39 | | - |
40 | | -```shell |
41 | | - docker extension install ngrok/ngrok-docker-extension:latest |
42 | | -``` |
43 | | - |
44 | | -> If you want to automate this command, use the `-f` or `--force` flag to accept the warning message. |
45 | | -
|
46 | | -To preview the extension in Docker Desktop, open Docker Dashboard once the installation is complete. The left-hand menu displays a new tab with the name of your extension. You can also use `docker extension ls` to see that the extension has been installed successfully. |
47 | | - |
48 | | -### Frontend development |
49 | | - |
50 | | -During the development of the frontend part, it's helpful to use hot reloading to test your changes without rebuilding your entire extension. To do this, you can configure Docker Desktop to load your UI from a development server. |
51 | | -Assuming your app runs on the default port, start your UI app and then run: |
52 | | - |
53 | | -```shell |
54 | | - cd ui |
55 | | - npm install |
56 | | - npm run dev |
57 | | -``` |
58 | | - |
59 | | -This starts a development server that listens on port `3000`. |
60 | | - |
61 | | -You can now tell Docker Desktop to use this as the frontend source. In another terminal run: |
62 | | - |
63 | | -```shell |
64 | | - docker extension dev ui-source ngrok/ngrok-docker-extension:latest http://localhost:3000 |
65 | | -``` |
66 | | - |
67 | | -In order to open the Chrome Dev Tools for your extension when you click on the extension tab, run: |
68 | | - |
69 | | -```shell |
70 | | - docker extension dev debug ngrok/ngrok-docker-extension:latest |
71 | | -``` |
72 | | - |
73 | | -Each subsequent click on the extension tab will also open Chrome Dev Tools. To stop this behaviour, run: |
74 | | - |
75 | | -```shell |
76 | | - docker extension dev reset ngrok/ngrok-docker-extension:latest |
77 | | -``` |
78 | | - |
79 | | -### Backend development (optional) |
80 | | - |
81 | | -This example defines an API in Go that is deployed as a backend container when the extension is installed. Note that an extension doesn't necessarily need a backend container, but in this example we include one for teaching purposes. |
82 | | - |
83 | | -Whenever you make changes in the [backend](./backend) source code, you will need to compile them and re-deploy a new version of your backend container. |
84 | | -Use the `docker extension update` command to remove and re-install the extension automatically: |
85 | | - |
86 | | -```shell |
87 | | -docker extension update felipecruz/ngrok-docker-extension:latest |
88 | | -``` |
89 | | - |
90 | | -> If you want to automate this command, use the `-f` or `--force` flag to accept the warning message. |
91 | | -
|
92 | | -> Extension containers are hidden from the Docker Dashboard by default. You can change this in Settings > Extensions > Show Docker Extensions system containers. |
93 | | -
|
94 | | -### Clean up |
95 | | - |
96 | | -To remove the extension: |
97 | | - |
98 | | -```shell |
99 | | -docker extension rm felipecruz/ngrok-docker-extension:latest |
100 | | -``` |
| 17 | +1. Start the container(s) you want to expose in Docker Desktop. |
| 18 | +2. Click on the Ngrok icon in the Docker Desktop toolbar. |
| 19 | +3. Authenticate with Ngrok by clicking "Authenticate" and pasting in your authtoken from the [Ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken). |
| 20 | +4. Start a tunnel by clicking start icon in the Ngrok extension window. |
| 21 | +5. You now have a public URL that you can share with anyone. |
101 | 22 |
|
102 | 23 | ## Screenshots |
103 | 24 | <img width="1292" alt="containers" src="https://user-images.githubusercontent.com/550861/222644761-b30982aa-e81a-4546-9678-dadfc731e0fc.png"> |
104 | | -<img width="1292" alt="settings" src="https://user-images.githubusercontent.com/550861/222644829-3b717704-5b58-455f-b729-dad4c96daf18.png"> |
105 | | - |
106 | | -## What's next? |
107 | | - |
108 | | -- To learn more about how to build your extension refer to the Extension SDK docs at https://docs.docker.com/desktop/extensions-sdk/. |
109 | | -- To publish your extension in the Marketplace visit https://www.docker.com/products/extensions/submissions/. |
110 | | -- To report issues and feedback visit https://github.com/docker/extensions-sdk/issues. |
| 25 | +<img width="1292" alt="settings" src="https://user-images.githubusercontent.com/550861/222644829-3b717704-5b58-455f-b729-dad4c96daf18.png"> |
0 commit comments