{"id":16630864,"url":"https://github.com/ryanclark/development","last_synced_at":"2025-08-05T08:15:22.846Z","repository":{"id":76218538,"uuid":"541745975","full_name":"ryanclark/development","owner":"ryanclark","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-04T10:05:54.000Z","size":2485,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-14T06:17:40.475Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryanclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-26T19:15:03.000Z","updated_at":"2025-07-04T10:05:36.000Z","dependencies_parsed_at":"2025-01-18T06:11:27.671Z","dependency_job_id":"7e2b5f98-9b04-4b78-83e6-a719f3251d30","html_url":"https://github.com/ryanclark/development","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ryanclark/development","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanclark%2Fdevelopment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanclark%2Fdevelopment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanclark%2Fdevelopment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanclark%2Fdevelopment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryanclark","download_url":"https://codeload.github.com/ryanclark/development/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanclark%2Fdevelopment/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268859123,"owners_count":24318874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-05T02:00:12.334Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T04:49:41.708Z","updated_at":"2025-08-05T08:15:22.774Z","avatar_url":"https://github.com/ryanclark.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Teleport Development Environment\n\nThis helps you run a local Teleport environment locally at https://go.teleport, with trusted local certificates (no\n`--insecure` anywhere).\n\nIt sets up a single Teleport service that runs the Auth and Proxy services, as well as a container to run Vite so you\ncan build both Teleport and the Web code at the same time. It also runs Application Access with the debug dumper app.\n\nFile changes for the Teleport repo are sync'd and then [air](https://github.com/cosmtrek/air) watches for any changes to\nyour local Teleport repo, and will rebuild and relaunch Teleport when you change a `.go` or `.yaml` file.\n\nThis uses caching for both Go and Vite, so although the first initial run will take a few minutes, subsequent runs\nof `make start` will build both Teleport and the frontend and have them up and running in \u003c5s.\n\n![make help](images/help.png)\n\n![Teleport](images/teleport.png)\n\n## Setup\n\n### Directory Setup\n\nThis assumes you have your local directory structure setup something like:\n\n```\n~/go/src/github.com/gravitational\n└── teleport\n│   └── api\n│   │   │ go.mod\n│   │   │ etc...\n│   │\n│   └── e\n│       └── lib\n│       └── tool\n│       └── web\n│       └── etc...\n│   │\n│   └── lib\n│   │\n│   └── tool\n│   │\n│   └── web\n│       └── packages\n│           └── teleport\n│       └── etc...\n│   │\n│   │ go.mod\n│   │ etc...\n```\n\nYou should clone this directory so it's next to `teleport`.\n\n```\n~/go/src/github.com/gravitational\n└── development\n│   └── frontend\n│   │   │ Dockerfile\n│   │\n│   └── teleport\n│       │ Dockerfile\n│   │\n│   │ docker-compose.yml\n│   │ etc...\n│\n└── teleport\n│   └── api\n│   │   │ go.mod\n│   │   │ etc...\n│   │\n│   └── e\n│       └── lib\n│       └── tool\n│       └── web\n│       └── etc...\n│   │\n│   └── lib\n│   │\n│   └── tool\n│   │\n│   └── web\n│       └── packages\n│           └── teleport\n│       └── etc...\n│   │\n│   │ go.mod\n│   │ etc...\n```\n\nYou don't have to have the enterprise submodules cloned if you do not want to build the enterprise version.\n\n### mkcert\n\nYou'll need [mkcert](https://github.com/FiloSottile/mkcert), which is a quick and easy way to create local, trusted\ncertificates.\n\nIf you're on macOS, you can install `mkcert` via\n\n```bash\nbrew install mkcert\n```\n\nYou should then run\n\n```bash\nmkcert -install\n```\n\nFinally, to setup the certificates we need, run:\n\n```bash\nmake cert\n```\n\n### Docker\n\nYou'll also need Docker running.\n\nFor an Apple Silicon Mac, I've found that enabling the new virtualization framework and therefore enabling VirtioFS\naccelerated directory sharing has yielded a very fast environment.\n\nYou should increase your Docker resource limits. Give it as much as you can spare, for the fastest performance building\nand running Teleport locally. The CPUs should be maybe n-1 or n-2 of your total available. Memory can probably be\nbetween 50-75% of what your machine has.\n\n### DNS resolution\n\nYou'll need `go.teleport` to resolve to `0.0.0.0`. If you're using a service like NextDNS, it's easy to do this in their\ncontrol panel.\n\nIf you aren't, you can `sudo vim /etc/hosts` and add:\n\n```\n0.0.0.0 go.teleport\n0.0.0.0 dumper.go.teleport\n```\n\nIf you wish to use a domain other than `go.teleport`, do a search and replace of any instance of `go.teleport` with the\ndomain you pick. This is because the Docker container's hostname and name need to match, so Teleport realises it's\nrunning normally (as the proxy address and host address aren't different), and doesn't try to launch you into an app and\nput you in an infinite redirect loop when you try to go to the web UI.\n\n## Running\n\nTo start, run:\n\n```bash\nmake start\n```\n\nThis will build the Docker containers if it's your first time running the command, and just start Teleport quickly if\nyou've already ran the command before and have stopped running Teleport since.\n\nThe containers will run in detached mode, so you won't have any logs immediately available to you in the console.\n\nYou might find it useful to download a tool such as [lazydocker](https://github.com/jesseduffield/lazydocker) which\nwill give you a CLI tool to view and manage all the Docker containers that are all running.\n\n```bash\nbrew install jesseduffield/lazydocker/lazydocker\n```\n\n![lazydocker logs](images/lazydocker-logs.png)\n\n![lazydocker stats](images/lazydocker-stats.png)\n\nOr, if you prefer a GUI, [DockStation](https://dockstation.io/) for Mac is also good.\n\n![DockStation logs](images/dockstation-logs.png)\n\n![DockStation stats](images/dockstation-stats.png)\n\nIf you wish to have all the logs visible to you in one go and attach your current terminal to Docker compose, you can run this instead:\n\n```bash\nmake start-attach\n```\n\nStopping this command will stop the development environment.\n\nThe Teleport container has `tctl` built as part of the build process. This speeds up the build of Teleport by air when\nthe container launches (as most of the Go packages have been downloaded and there's a populated Go cache), as well as\nprovides `tctl` to be able to create the initial first user.\n\nOnce Teleport has finished initializing, you can run:\n\n```bash\nmake setup\n```\n\nWhich will create the initial admin user for you.\n\n### Logs\n\nTo get and follow the logs from the frontend or the logs from Teleport, you can run\n\n```bash\nmake frontend-logs\nmake teleport-logs\n```\n\nTo get any other logs you can run\n\n```bash\nmake logs servicename # or\nmake logs -- -f servicename # -- is needed when passing in flags (such as -f for follow)\n```\n\n### Stopping\n\nTo stop the running Docker contains, run:\n\n```bash\nmake stop\n```\n\n### Swapping between Teleport versions\n\nAs this lives next to your `teleport` and `webapps` directories, you can just checkout whatever branch you need to work\non in either repo.\n\n#### teleport\n\nWhen changing the major version of `teleport`, you should re-run `make build`. This is because `tctl` is built to live\ninside the container, as is `teleport` if you're using static services that don't live reload.\n\n`tctl` and `teleport` change quite a bit between major versions, so a rebuild ensures these binaries are on the same\nmajor version that the live reloading services are on.\n\n#### webapps\n\nWhen changing the major version of `webapps`, you should make sure you run `yarn` inside `webapps` before\nre-running `make start`. There shouldn't be any need to run `make build`.\n\n### Building Enterprise\n\nTo build the enterprise version of `tctl`, `teleport` and the frontend, create a file called `.e`.\n\nYou'll want to run `make build` first before re-running `make start` when swapping between enterprise and OSS.\n\n\u003e You can choose not to run a build to just swap the frontend between OSS and Enterprise, but a rebuild is needed for\n\u003e the `tctl` and `teleport` binaries inside the containers.\n\u003e\n\u003e If you're using live-reload defined services, you may not need to rebuild as the presence of the `.e` file tells air\n\u003e to build either the OSS or Enterprise. The `tctl` binary in the container will still be incorrect, however.\n\u003e\n\u003e If you're using static defined services, you will need to rebuild.\n\n### Commands\n\n#### Opening a shell\n\nYou can open an interactive shell to either the frontend or Teleport via:\n\n```\nmake teleport-shell\nmake frontend-shell\n```\n\n#### tctl\n\n`tctl` lives inside the Teleport container, so to run the equivalent of `tctl get users`, you can run:\n\n```bash\nmake tctl get users\n```\n\n### Adding another Teleport service\n\nThe quickest way to add another Teleport node is to extend `node` from `base/docker-compose.yml`. You just need to\ncreate a new folder for the node (e.g. `node2`) with a `teleport.yaml` file inside - you can copy the existing one\nfrom `node/teleport.yml` and adjust `teleport.nodename`.\n\nThen, in `docker-compose.yml`, add something like\n\n```yaml\n  node2:\n    container_name: node2 # for the sake of not having it named `development-node2-1`\n    hostname: node2 # set the hostname to node2 also\n    extends:\n      file: base/docker-compose.yml\n      service: node\n    volumes:\n      - ./data/node2:/var/lib/teleport\n      - ./node2/teleport.yaml:/etc/teleport.yaml\n```\n\nIn the `docker-compose.yml`, you'll see there are two types of Teleport services running, and they're defined a little\ndifferently.\n\n#### Services that rebuild on code changes\n\nIf you want to rebuild Teleport on every file change, you'll want to copy how the Auth Service (`go.teleport`) is setup,\nlike this:\n\n```yaml\n  service-name:\n    container_name: service-name\n    build:\n      dockerfile: development/build/Dockerfile\n      context: ..\n      target: live-reload\n    volumes:\n      - ../teleport:/app/:rw,delegated\n      - ./data/cache/service-name/go-pkg:/go/pkg/mod:rw,delegated\n      - ./data/cache/service-name/go:/root/.cache/go-build,delegated\n      - ./data/service-name:/var/lib/teleport\n      - ./build/.air.toml:/app/.air.toml\n      - ./service-name/teleport.yaml:/etc/teleport.yaml\n```\n\nAnd create a folder called `\u003cservice-name\u003e` with a `teleport.yaml` inside, configured how you need it to be. You might\nfind it useful to add a static token to `teleport/teleport.yaml`, so the Teleport service can instantly join the Auth\nService.\n\nThe key things in this config are the `target` being `live-reload` - this uses the `Dockerfile` up until it's\nbuilt `tctl`, and then `air` will run which will build Teleport, start it, and rebuild it and restart it on file\nchanges.\n\n#### Services that do not need to rebuild on code changes\n\nIf you're only working the Auth Service code, it would be a bit annoying if you were running an SSH agent and that also\nkept rebuilding, even though you're not editing the code.\n\nTo setup a service in this way, copy the configuration for the `node` service in `docker-compose.yml`.\n\n```yaml\n  service-name:\n    container_name: service-name\n    build:\n      dockerfile: development/build/Dockerfile\n      context: ..\n      target: static\n    volumes:\n      - ./data/service-name:/var/lib/teleport\n      - ./service-name/teleport.yaml:/etc/teleport.yaml\n```\n\nThe `target` that's specified is now `static`, which will build `tctl`, skip past `air`, build `teleport` and the\nrun `teleport start -d`. This means you now have a static instance which won't respond to code changes.\n\nYou'll still need to create a folder for `\u003cservice-name\u003e` with a `teleport.yaml` file like mentioned above.\n\n### Other info\n\n#### Only running Teleport, not Vite too\n\nYou can go into \"solo\" mode, where Vite isn't running alongside Teleport and instead you're just getting the\nwebassets built into the Teleport binary.\n\nTo do this, create a file called `.solo`. The presence of this file will result in `docker-compose.solo.yml` being the\ncompose file (so all `make` targets will still work with the different file) and you'll be running Teleport without\nVite in front.\n\nWhen swapping between solo mode and normal, you just need to re-run `make start`. There's nothing that needs to be\nrebuilt.\n\n#### Config File\n\nThe config file for Teleport is in `teleport/teleport.yaml`. This is volume mounted into the container, so if Teleport\nis meant to react to a config change whilst running, you'll see this behavior.\n\nIf you need to change the config that requires a restart of Teleport, just stop your `make start` and re-run it.\n\n#### Teleport License\n\nWhen enterprise is enabled, this builds the Enterprise version of both Teleport and Webapps. It pulls in the enterprise\nlicense will full features by default, but if you wish to change it to any of\nthe [other license types](https://github.com/gravitational/teleport.e/tree/master/fixtures), you can just change the\nfile name that's mounted in `docker-compose.yml`.\n\n#### Rebuilding the Docker image\n\nIf you need to rebuild `tctl` or rebuild the Docker images for whatever reason, you can run\n\n```bash\nmake build\n```\n\nYou'll then need to re-run `make start`.\n\nTo completely wipe your workspace, run:\n\n```bash\nmake clean\n```\n\nWhich will remove all containers and volumes created by Docker.\n\n#### Make commands reference\n\nYou can also run `make help` to get a list of the available Make targets.\n\n**Controlling container lifecycle**\n\n- `make start` - starts (and builds, if not present) the Docker containers in detached mode\n- `make start-attach` - starts (and builds, if not present) the Docker containers and attaches to the output of them\n- `make stop` - stops all containers\n\n**Building \u0026 cleaning**\n\n- `make build` - builds/rebuilds the Docker images\n- `make clean` - removes all Docker containers and volumes\n- `make down` - removes all Docker containers\n\n**Setup**\n\n- `make cert` - creates the self-signed certificate for `go.teleport` and `*.teleport` with `mkcert`\n- `make setup` - sets up the default admin user via an alias\n  to `make tctl users add admin --roles=editor,access --logins=root,ubuntu,ec2-user`\n\n**Commands**\n\n- `make frontend-logs` - alias for `make logs -- -f frontend`\n- `make frontend-shell` - open an interactive shell inside the frontend container\n- `make logs \u003ccommand\u003e` - runs `docker compose logs \u003ccommand\u003e`\n- `make tctl \u003ccommand\u003e` - runs `tctl` inside the Teleport container\n- `make teleport-logs` - alias for `make logs -- -f go.teleport`\n- `make teleport-shell` - open an interactive shell inside the Teleport container\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanclark%2Fdevelopment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanclark%2Fdevelopment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanclark%2Fdevelopment/lists"}