2019-09-20 19:13:48 +00:00
# Gravitational Web Applications and Packages
2023-01-23 11:50:16 +00:00
This directory contains the source code for:
2022-06-15 15:01:26 +00:00
2022-06-22 20:58:56 +00:00
- the web UIs served by the `teleport` server
2023-01-23 11:50:16 +00:00
- [`packages/teleport` ](packages/teleport )
2022-06-22 20:58:56 +00:00
- the Electron app of [Teleport Connect ](https://goteleport.com/connect/ )
- [`packages/teleterm` ](packages/teleterm )
2019-09-20 19:13:48 +00:00
The code is organized in terms of independent yarn packages which reside in
2023-01-23 11:50:16 +00:00
the [packages directory ](packages ).
2019-09-20 19:13:48 +00:00
2022-06-15 15:01:26 +00:00
## Getting Started with Teleport Web UI
2019-09-20 19:13:48 +00:00
You can make production builds locally or you can use Docker to do that.
### Local Build
2020-01-22 20:26:35 +00:00
2019-09-20 19:13:48 +00:00
Make sure that [you have yarn installed ](https://yarnpkg.com/lang/en/docs/install/#debian-stable )
on your system since this monorepo uses the yarn package manager.
Then you need download and initialize these repository dependencies.
```
$ yarn install
```
2021-01-21 06:19:39 +00:00
To build the Teleport open source version
2019-09-20 19:13:48 +00:00
```
2023-01-23 11:50:16 +00:00
$ yarn build-ui-oss
2019-09-20 19:13:48 +00:00
```
2023-03-21 18:01:53 +00:00
The resulting output will be in the `webassets` folder.
2019-09-20 19:13:48 +00:00
### Docker Build
2021-01-21 06:23:35 +00:00
To build the Teleport community version
2020-01-22 20:26:35 +00:00
2019-09-20 19:13:48 +00:00
```
2023-01-23 11:50:16 +00:00
$ make docker-ui
2019-09-20 19:13:48 +00:00
```
2022-06-15 15:01:26 +00:00
## Getting Started with Teleport Connect
2023-01-23 11:50:16 +00:00
See [`README.md` in `packages/teleterm` ](packages/teleterm#readme ).
2022-06-15 15:01:26 +00:00
2019-09-20 19:13:48 +00:00
## Development
2020-01-22 20:26:35 +00:00
2023-03-21 18:01:53 +00:00
### Local HTTPS
2019-09-20 19:13:48 +00:00
2023-03-21 18:01:53 +00:00
To run `vite` for either Teleport or Teleport enterprise, you'll need to generate local
self-signed certificates. The recommended way of doing this is via [mkcert ](https://github.com/FiloSottile/mkcert ).
2019-09-20 19:13:48 +00:00
2023-03-21 18:01:53 +00:00
You can install mkcert via
2019-09-20 19:13:48 +00:00
```
2023-03-21 18:01:53 +00:00
brew install mkcert
2019-09-20 19:13:48 +00:00
```
2023-03-21 18:01:53 +00:00
After you've done this, run:
2022-07-25 15:57:07 +00:00
```
2023-03-21 18:01:53 +00:00
mkcert -install
2022-07-25 15:57:07 +00:00
```
2023-03-21 18:01:53 +00:00
This will generate a root CA on your machine and automatically trust it (you'll be prompted for your password).
Once you've generated a root CA, you'll need to generate a certificate for local usage.
2022-09-28 12:05:12 +00:00
2023-03-21 18:01:53 +00:00
Run the following from the `web/` directory, replacing `localhost` if you're using a different hostname.
2022-09-28 12:05:12 +00:00
```
2023-03-21 18:01:53 +00:00
mkdir -p certs & & mkcert -cert-file certs/server.crt -key-file certs/server.key localhost "*.localhost"
2022-09-28 12:05:12 +00:00
```
2023-03-21 18:01:53 +00:00
(Note: the `certs/` directory in this repo is ignored by git, so you can place your certificate/keys
in there without having to worry that they'll end up in a commit.)
2022-08-26 15:49:10 +00:00
2023-03-21 18:01:53 +00:00
#### Certificates in an alternative location
2022-08-26 15:49:10 +00:00
2023-03-21 18:01:53 +00:00
If you already have local certificates, you can set the environment variables:
2022-08-26 15:49:10 +00:00
2023-03-21 18:01:53 +00:00
- `VITE_HTTPS_CERT` ** (required)** - absolute path to the certificate
- `VITE_HTTPS_KEY` ** (required)** - absolute path to the key
2022-08-26 15:49:10 +00:00
You can set these in your `~/.zshrc` , `~/.bashrc` , etc.
```
2023-03-21 18:01:53 +00:00
export VITE_HTTPS_CERT=/Users/you/certs/server.crt
export VITE_HTTPS_KEY=/Users/you/certs/server.key
2022-08-26 15:49:10 +00:00
```
2023-03-21 18:01:53 +00:00
### Web UI
2022-11-09 14:55:51 +00:00
2023-03-21 18:01:53 +00:00
To avoid having to install a dedicated Teleport cluster,
you can use a local development server which can proxy network requests
to an existing cluster.
2022-11-09 14:55:51 +00:00
2023-03-21 18:01:53 +00:00
For example, if `https://example.com:3080` is the URL of your cluster then:
2022-11-09 14:55:51 +00:00
2023-03-21 18:01:53 +00:00
To start your local Teleport development server
2022-11-09 14:55:51 +00:00
```
2023-03-21 18:01:53 +00:00
PROXY_TARGET=example.com:3080 yarn start-teleport
2022-11-09 14:55:51 +00:00
```
2023-03-21 18:01:53 +00:00
If you're running a local cluster at `https://localhost:3080` , you can just run
2022-11-09 14:55:51 +00:00
```
2023-03-21 18:01:53 +00:00
yarn start-teleport
2022-11-09 14:55:51 +00:00
```
2023-03-21 18:01:53 +00:00
This service will serve your local javascript files and proxy network
requests to the given target.
2022-11-15 10:15:06 +00:00
2023-03-21 18:01:53 +00:00
> Keep in mind that you have to use a local user because social
> logins (google/github) are not supported by development server.
2022-11-15 10:15:06 +00:00
2019-09-20 19:13:48 +00:00
### Unit-Tests
We use [jest ](https://jestjs.io/ ) as our testing framework.
To run all jest unit-tests:
2020-01-22 20:26:35 +00:00
2019-09-20 19:13:48 +00:00
```
$ yarn run test
```
To run jest in watch-mode
2020-01-22 20:26:35 +00:00
2019-09-20 19:13:48 +00:00
```
$ yarn run tdd
```
### Interactive Testing
We use [storybook ](https://storybook.js.org/ ) for our interactive testing.
It allows us to browse our component library, view the different states of
each component, and interactively develop and test components.
To start a storybook:
2020-01-22 20:26:35 +00:00
2019-09-20 19:13:48 +00:00
```
2019-11-20 18:14:28 +00:00
$ yarn run storybook
2019-09-20 19:13:48 +00:00
```
This command will open a new browser window with storybook in it. There
you will see components from all packages so it makes it faster to work
2019-11-20 18:14:28 +00:00
and iterate on shared functionality.
2020-04-02 18:49:53 +00:00
2020-04-16 05:43:05 +00:00
### Setup Prettier on VSCode
1. Install plugin: https://github.com/prettier/prettier-vscode
1. Go to Command Palette: CMD/CTRL + SHIFT + P (or F1)
1. Type `open settings`
1. Select `Open Settings (JSON)`
1. Include the below snippet and save:
```js
2021-04-23 21:59:40 +00:00
// Set the default
"editor.formatOnSave": false,
// absolute config path
"prettier.configPath": ".prettierrc",
// enable per-language
"[html]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascript]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascriptreact]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[typescript]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[json]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "vscode.json-language-features"
},
"[jsonc]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "vscode.json-language-features"
},
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
2020-04-16 05:43:05 +00:00
"editor.tabSize": 2,
2020-09-15 18:45:23 +00:00
```
2022-02-22 19:50:55 +00:00
### MFA Development
When developing MFA sections of the codebase, you may need to configure the `teleport.yaml` of your target teleport cluster to accept hardware keys registered over the local development setup. Webauthn can get tempermental if you try to use localhost as your `rp_id` , but you can get around this by using https://nip.io/. For example, if you want to configure optional `webauthn` mfa, you can set up your auth service like so:
```yaml
auth_service:
authentication:
type: local
second_factor: optional
webauthn:
2022-06-22 20:58:56 +00:00
rp_id: proxy.127.0.0.1.nip.io
2022-02-22 19:50:55 +00:00
2022-04-05 00:56:49 +00:00
proxy_service:
enabled: yes
# setting public_addr is optional, useful if using different port e.g. 8080 instead of default 3080
2022-06-22 20:58:56 +00:00
public_addr: ['proxy.127.0.0.1.nip.io']
2022-02-22 19:50:55 +00:00
```
2022-06-22 20:58:56 +00:00
Then start the dev server like `yarn start-teleport --target=https://proxy.127.0.0.1.nip.io:3080` and access it at https://proxy.127.0.0.1.nip.io:8080.
2022-07-15 15:26:31 +00:00
### Adding Packages/Dependencies
We use Yarn Workspaces to manage dependencies.
- [Introducing Workspaces ](https://yarnpkg.com/blog/2017/08/02/introducing-workspaces )
- [Workspaces Documentation ](https://yarnpkg.com/en/docs/workspaces )
The easiest way to add a package is to add a line to the workspace's `package.json` file and then run `yarn install` from
the root of this repository.
Keep in mind that there should only be a single `yarn.lock` in this repository, here at the top level. If you add packages
via `yarn workspace <workspace-name> add <package-name>` , it will create a `packages/<package-name>/yarn.lock` file, which should not be checked in.
2022-07-22 15:37:10 +00:00
### Adding an Audit Event
When a new event is added to Teleport, the web UI has to be updated to display it correctly:
1. Add a new entry to [`eventCodes` ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/services/audit/types.ts ).
2. Add a new entry to [`RawEvents` ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/services/audit/types.ts ) using the event you just created as the key. The fields should match the fields of the metadata fields on `events.proto` on Teleport repository.
3. Add a new entry in [Formatters ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/services/audit/makeEvent.ts ) to format the event on the events table. The `format` function will receive the event you added to `RawEvents` as parameter.
4. Define an icon to the event on [`EventIconMap` ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/Audit/EventList/EventTypeCell.tsx ).
5. Add an entry to the [`events` ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/Audit/fixtures/index.ts ) array so it will show up on the [`AllEvents` story ](https://github.com/gravitational/webapps/blob/8a0201667f045be7a46606189a6deccdaee2fe1f/packages/teleport/src/Audit/Audit.story.tsx )
2022-12-13 21:11:54 +00:00
6. Check fixture is rendered in storybook, then update snapshot for `Audit.story.test.tsx` using `yarn test-update-snapshot` .
2022-07-22 15:37:10 +00:00
You can see an example in [this pr ](https://github.com/gravitational/webapps/pull/561 ).