This directory contains the source code for:
- the web UIs served by the
teleportserver - the Electron app of Teleport Connect
The code is organized in terms of independent yarn packages which reside in the packages directory.
You can make production builds locally or you can use Docker to do that.
Make sure that you have yarn installed on your system since this monorepo uses the yarn package manager.
Then you need download and initialize these repository dependencies.
$ yarn install
You will also need the following tools installed:
- The
RustandCargoversion in build.assets/Makefile (search forRUST_VERSION) are required. - The
wasm-packversion in build.assets/Makefile (search forWASM_PACK_VERSION) is required:curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh binaryen(which containswasm-opt) is required to be installed manually on linux aarch64 (64-bit ARM). You can check if it's already installed on your system by runningwhich wasm-opt. If not you can install it likeapt-get install binaryen(for Debian-based Linux).wasm-packwill install this automatically on other platforms.
To build the Teleport open source version
$ yarn build-ui-oss
The resulting output will be in the webassets folder.
To build the Teleport community version
$ make docker-ui
See README.md in packages/teleterm.
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.
You can install mkcert via
brew install mkcert
After you've done this, run:
mkcert -install
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.
Run the following from the web/ directory, replacing localhost if you're using a different hostname.
mkdir -p certs && mkcert -cert-file certs/server.crt -key-file certs/server.key localhost "*.localhost"
(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.)
If you already have local certificates, you can set the environment variables:
VITE_HTTPS_CERT(required) - absolute path to the certificateVITE_HTTPS_KEY(required) - absolute path to the key
You can set these in your ~/.zshrc, ~/.bashrc, etc.
export VITE_HTTPS_CERT=/Users/you/certs/server.crt
export VITE_HTTPS_KEY=/Users/you/certs/server.key
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.
For example, if https://example.com:3080 is the URL of your cluster then:
To start your local Teleport development server
PROXY_TARGET=example.com:3080 yarn start-teleport
If you're running a local cluster at https://localhost:3080, you can just run
yarn start-teleport
This service will serve your local javascript files and proxy network requests to the given target.
Keep in mind that you have to use a local user because social logins (google/github) are not supported by development server.
The web UI includes a WASM module built from a Rust codebase located in packages/teleport/src/ironrdp.
It is built with the help of wasm-pack.
Running yarn build-wasm builds the WASM binary as well as the appropriate Javascript/Typescript
bindings and types in web/packages/teleport/src/ironrdp/pkg.
We use jest as our testing framework.
To run all jest unit-tests:
$ yarn run test
To run jest in watch-mode
$ yarn run tdd
We use storybook 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:
$ yarn run storybook
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 and iterate on shared functionality.
We are targeting last 2 versions of all major browsers. To quickly find out which ones exactly, use the following command:
$ yarn browserslist 'last 2 chrome version, last 2 edge version, last 2 firefox version, last 2 safari version'
- Install plugin: https://github.com/prettier/prettier-vscode
- Go to Command Palette: CMD/CTRL + SHIFT + P (or F1)
- Type
open settings - Select
Open Settings (JSON) - Include the below snippet and save:
// 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",
},
"editor.tabSize": 2,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:
auth_service:
authentication:
type: local
second_factor: optional
webauthn:
rp_id: proxy.127.0.0.1.nip.io
proxy_service:
enabled: yes
# setting public_addr is optional, useful if using different port e.g. 8080 instead of default 3080
public_addr: ['proxy.127.0.0.1.nip.io']Then start the dev server like PROXY_TARGET=https://proxy.127.0.0.1.nip.io:3080 yarn start-teleport and access it at https://proxy.127.0.0.1.nip.io:8080.
We use Yarn Workspaces to manage dependencies.
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.
When a new event is added to Teleport, the web UI has to be updated to display it correctly:
- Add a new entry to
eventCodes. - Add a new entry to
RawEventsusing the event you just created as the key. The fields should match the fields of the metadata fields onevents.protoon Teleport repository. - Add a new entry in Formatters to format the event on the events table. The
formatfunction will receive the event you added toRawEventsas parameter. - Define an icon to the event on
EventIconMap. - Add an entry to the
eventsarray so it will show up on theAllEventsstory - Check fixture is rendered in storybook, then update snapshot for
Audit.story.test.tsxusingyarn test-update-snapshot.
You can see an example in this pr.