This mono-repository contains the source code for:
- the web UIs served by the
teleport
serverpackages/teleport
for the OSS versionpackages/webapps.e/teleport
for the enterprise version
- the Electron app of Teleport Connect
packages/teleterm
packages/webapps.e/teleterm
for the enterprise version
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
To build the Teleport open source version
$ yarn build-teleport-oss
The resulting output will be in the /packages/{package-name}/dist/
folders respectively.
To build the Teleport community version
$ make build-teleport-oss
See README.md
in packages/teleterm
.
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/web
is the URL of your cluster then:
To start your local Teleport development server
$ yarn start-teleport --target=https://example.com:3080/web
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.
By default, Webpack will store a cache in node_modules/.cache/webpack
during development. This
makes starting webpack-dev-server
really quick after having ran it once, as it will re-use the
cache from the last time it was running.
If you want to change the location of the cache, you can set WEBPACK_CACHE_DIRECTORY
to an
absolute file path of the folder where you want to store Webpack's cache.
If you wish to disable the cache, you can set WEBPACK_CACHE_DISABLED
to yes
.
During development, Webpack will default to generating source maps using eval-source-map
.
This can be overridden by setting the WEBPACK_SOURCE_MAP
environment variable to one of the
available values that Webpack offers.
To turn them off, set WEBPACK_SOURCE_MAP
to none
-
$ WEBPACK_SOURCE_MAP=none yarn start-teleport --target=https://example.com:3080/web
To make Webpack listen on a different port, you can set the WEBPACK_PORT
environment variable
to whatever port you need.
$ WEBPACK_PORT=6060 yarn start-teleport --target=https://example.com:3080/web
If you'd like to provide your own key/certificate for Webpack's development server, you can override the default behavior by setting some environment variables.
You should either set:
WEBPACK_HTTPS_CERT
(required) - absolute path to the certificateWEBPACK_HTTPS_KEY
(required) - absolute path to the keyWEBPACK_HTTPS_CA
- absolute path to the caWEBPACK_HTTPS_PASSPHRASE
- the passphrase
Or:
WEBPACK_HTTPS_PFX
(required) - absolute path to the certificateWEBPACK_HTTPS_PASSPHRASE
- the passphrase
You can set these in your ~/.zshrc
, ~/.bashrc
, etc.
export WEBPACK_HTTPS_CERT=/Users/you/go/src/github.com/gravitational/webapps/certs/server.crt
export WEBPACK_HTTPS_KEY=/Users/you/go/src/github.com/gravitational/webapps/certs/server.key
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.
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.
- 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 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.
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
RawEvents
using the event you just created as the key. The fields should match the fields of the metadata fields onevents.proto
on Teleport repository. - Add a new entry in Formatters to format the event on the events table. The
format
function will receive the event you added toRawEvents
as parameter. - Define an icon to the event on
EventIconMap
. - Add an entry to the
events
array so it will show up on theAllEvents
story - Check fixture is rendered in storybook, then update snapshot for
Audit.story.test.tsx
You can see an example in this pr.