Skip to content

Commit 7caf1e3

Browse files
committed
adds advanced routing guide
1 parent 20923bb commit 7caf1e3

File tree

5 files changed

+151
-12
lines changed

5 files changed

+151
-12
lines changed

content/docs/courses/zero-fundamentals/advanced-routes.mdx

+151-12
Original file line numberDiff line numberDiff line change
@@ -153,19 +153,158 @@ After applying your changeset, check the request headers in HTTPBin again. You'l
153153

154154
`"Host": "httpbin.righteous-gemstone-1734.pomerium.app"`
155155
156-
## Redirects and Direct Response
156+
## Test Advanced settings
157157
158-
RESUME HERE
158+
### Redirects
159159
160+
TODO
160161
162+
### Direct Response
161163
162-
[
163-
Goals:
164-
- Build advanced routes
165-
- Request headers
166-
- Response headers
167-
- Host headers
168-
- Redirects
169-
- Direct response
170-
- Prefix and Path settings
171-
]
164+
TODO
165+
You can configure Pomerium to send a small, static HTTP response to the downstream client for a managed route.
166+
167+
## Test prefix and path settings
168+
169+
### Configure Node server
170+
171+
To demonstrate these settings, you need to add a simple Node HTTP server to your Docker Compose file.
172+
173+
First, make sure you install [Node.js](https://nodejs.org/en/download).
174+
175+
After you've installed Node.js:
176+
177+
1. Create a new directory called `app` and `cd` into it
178+
1. Initiate a Node application: `npm init`
179+
1. Create an `index.js` file: `touch index.js`
180+
1. Install Express: `npm i express`
181+
182+
Add the following code inside `index.js`:
183+
184+
```js title="index.js"
185+
const express = require('express');
186+
const app = express();
187+
188+
app.get('/', (req, res) => {
189+
res.send('Hello World!');
190+
});
191+
192+
app.get('/admin', (req, res) => {
193+
res.send('This is an admin only page');
194+
});
195+
196+
app.listen(5001, () => console.log('Server is up and running'));
197+
```
198+
199+
This mini server builds two different endpoints:
200+
201+
- `/`
202+
- `/admin`
203+
204+
Your `app` directory should now have a `package.json` file and a `node_modules` folder.
205+
206+
Next, test your server:
207+
208+
```bash
209+
node index.js
210+
```
211+
212+
Navigate to `localhost:5001` to see if your server serves the `Hello World!` message. Similarly, if you go to `localhost:5001/admin`, you should see `This is an admin only page`.
213+
214+
![Testing the Node HTTP server's admin and public endpoint responses](./img/advanced-routes/server-endpoints.gif)
215+
216+
#### Dockerize Node server
217+
218+
Next, we will Dockerize our Node server. In the `./app` directory, create the following files:
219+
220+
```bash
221+
touch Dockerfile && touch .dockerignore
222+
```
223+
224+
In `Dockerfile`, add the following instructions:
225+
226+
```yaml title="Dockerfile"
227+
# pull the Node.js Docker image
228+
FROM node:alpine
229+
230+
# create the directory inside the container
231+
WORKDIR /usr/src/app
232+
233+
# copy the package.json files from local machine to the workdir in container
234+
COPY package*.json ./
235+
236+
# run npm install in our local machine
237+
RUN npm install
238+
239+
# copy the generated modules and all other files to the container
240+
COPY . .
241+
242+
# our app is running on port 5001 within the container, so need to expose it
243+
EXPOSE 5001
244+
245+
# the command that starts our app
246+
CMD ["node", "index.js"]
247+
```
248+
249+
In `.dockerignore`, add:
250+
251+
```yaml title=".dockerignore"
252+
node_modules npm-debug.log
253+
```
254+
255+
In Docker Compose, add your Node server:
256+
257+
```yaml title="docker-compose.yaml"
258+
nodeserver:
259+
networks:
260+
main: {}
261+
build:
262+
context: ./app
263+
ports:
264+
- 5001:5001
265+
```
266+
267+
In the Zero Console, add a route and point it to `nodeserver`. For example:
268+
269+
![Adding the nodeserver route in the Zero Console](./img/advanced-routes/node-server-route.png)
270+
271+
Save your changes and apply your changeset. Then, test your route.
272+
273+
### Path Matching: Prefix
274+
275+
Assuming your route works, we will configure the [**Prefix**](/docs/reference/routes/path-matching#prefix) setting.
276+
277+
The `prefix` setting instructs Pomerium to only match the route if the incoming request has the specified prefix in its path.
278+
279+
In the Zero Console:
280+
281+
1. Go to your Node server route
282+
1. Select **Path Matching**
283+
1. In the **Prefix** field, enter `/admin`
284+
285+
If you append the `/admin` endpoint to your route, Pomerium should direct you to the `/admin` only page. If you don't append `/admin`, you will see a 404 error:
286+
287+
![Adding the /admin prefix to the Node server route](./img/advanced-routes/nodeserver-prefix-setting.gif)
288+
289+
### Path Rewriting: Prefix Rewrite
290+
291+
Next, let’s add [**Prefix Rewrite**](/docs/reference/routes/path-rewriting#prefix-rewrite).
292+
293+
In the Zero Console:
294+
295+
1. Select **Path Rewriting**
296+
1. In the **Prefix Rewrite** field, enter a `/`
297+
298+
If the incoming request’s prefix matches the value of `prefix` (`/admin`), Pomerium will rewrite `prefix` to match the value of `prefix_rewrite`.
299+
300+
Now, if you navigate to the `/admin` endpoint, Pomerium will redirect you to the `/` page. If you don’t include the `/admin` prefix, the request will `404`.
301+
302+
![Adding the / prefix rewrite setting to the Node server route](./img/advanced-routes/nodeserver-prefix-rewrite-setting.gif)
303+
304+
Great job! You've configured several advanced routes in Pomerium Zero.
305+
306+
## Up Next: TCP Routes
307+
308+
In the next guide, you'll secure TCP routes and access an SSH service.
309+
310+
Go to [TCP Routes](/docs/courses/zero-fundamentals/tcp-ssh).
Loading
Loading
Loading

0 commit comments

Comments
 (0)