Skip to content

Quality Example Templates #2179

Closed
Closed

Description

@spikecurtis

This epic tracks multiple issues regarding our example templates, and what it would take to bring them up to a quality that represents a good experience for first time users.

General Requirements:

  • run as a standard user, not root
  • persistent home directory
  • includes code-server
  • JetBrains Gateway runs against them

Activity

  1. spikecurtis commented on Jun 13, 2022

    @spikecurtis
    CollaboratorAuthor

    @tjcran @ketang

    We need to talk at a high level about what the requirements are for the example templates. There are a lot of wants here and it's not possible to achieve all of them with just a flat set of templates.

    My initial goal in writing this epic was geared toward optimizing the templates for first time users of Coder:

    • minimize the time from install to writing some code
    • choose sensible defaults so they get a powerful, smooth experience
    • showcase cool Coder features like dotfiles, etc

    Since then in individual tickets there have been comments about other, different goals for templates, and I want to elevate the conversation and talk holistically here. For example, for both dotfiles and code-server I've heard, hey maybe we don't want to include it, or not everywhere because not everyone wants it. Here we start to get into what I think are other goals for templates like

    • helping people learn how Coder works and what is required
    • helping teams deploying Coder for production use by providing "base" templates they can build from, rather than force them to strip out things

    So, for one thing, let's try to enumerate what we are trying to accomplish at a high level.

    I'm starting to worry that different requirements for different people will lead to a combinatorial explosion of templates (infra provider * dotfiles-or-no * code-server-or-no * machine sizes is already huge). So, we need to either whittle down the list of things we're trying to accomplish with example templates, or consider some kind of "meta-template" where we ask the user questions like, "what infra?" and spit out a workspace template that is fairly close to what they want.

  2. tjcran commented on Jun 13, 2022

    @tjcran

    @spikecurtis thanks for making this epic, I think you're spot on that we need to align on the purpose. I'd like to include @bpmct @kylecarbs in this thread as well as stakeholders who are involved in the templates.

    I had previously agreed it should be a "base" that they can build from and see how Coder works.

    Because of that, we're currently at a point where the templates will not work out of the box for most folks, and we indicate as such, but we could go in a few different directions. We intentionally made it so they would likely need to modify it to get it working. But we could make it a better out of the box experience if we wanted to go in that route. And maybe we should.

    Enterprises are going to make their own templates regardless, so our example templates probably shouldn't optimize for the Enterprise and should perhaps optimize for the Community.

    And having easy out of the box templates that community members can grab to get immediately up and running is probably the direction I'd want to go (and we already are with the docker-compose).

  3. tjcran commented on Jun 13, 2022

    @tjcran

    The more I think about this the more I think maybe we should just completely optimize for out of the box working experience, which also means we consider code-server in most of the examples. (maybe have a jetbrains example template too which doesn't have code-server)

  4. kylecarbs commented on Jun 13, 2022

    @kylecarbs
    Member

    I agree with Spike's limited set of additions.

    Templates should be a sensible base for someone to work with on their infrastructure, not a featureful environment that is ready to go. For code-server, projector, and other niceties, users can reference other templates that may include that. I think having a single template that shows how to add an app is reasonable, but it certainly shouldn't be in every template.

  5. bpmct commented on Jun 13, 2022

    @bpmct
    Member

    I don't have a very clear opinion here, so will defer to others.

    A "meta template" or GUI-based configuration wizard that creates a template and spits out the source would eventually be necessary for people who don't want to write Terraform.

  6. tjcran commented on Jun 13, 2022

    @tjcran

    I think the concept is pretty similar to how cloud providers use machine images. There's a library of examples that some users (typically individuals or small teams) will just want to pick up and play. And large teams or enterprise will either modify heavily or just do their own thing from scratch.

    I like the list Spike started and will elaborate and add to it:

    • non root
    • if your cloud infra is pretty standard, the template works out of the box. If you're doing more advanced things, you'll have to modify to get it working
    • variety of examples to cover a variety of basic use cases, but not too many that the choice is overwhelming. we can add more as a specific request gains traction
    • code-server added, where it makes sense
    • LATER: wizard thingy

    I also am aligned with these points:

    My initial goal in writing this epic was geared toward optimizing the templates for first time users of Coder:

    • minimize the time from install to writing some code
    • choose sensible defaults so they get a powerful, smooth experience
    • showcase cool Coder features like dotfiles, etc

    Since then in individual tickets there have been comments about other, different goals for templates, and I want to elevate the conversation and talk holistically here. For example, for both dotfiles and code-server I've heard, hey maybe we don't want to include it, or not everywhere because not everyone wants it. Here we start to get into what I think are other goals for templates like

    • helping people learn how Coder works and what is required
    • helping teams deploying Coder for production use by providing "base" templates they can build from, rather than force them to strip out things
  7. spikecurtis commented on Jun 13, 2022

    @spikecurtis
    CollaboratorAuthor

    It doesn't sound like we are yet aligned at the high level, so let's get there before we start talking about individual features of templates. My hope is that these will be uncontroversial once we are aligned on purpose.

    So far I've heard support for both "templates should be a sensible base" and "templates should be a featureful out of the box experience." Is this worth discussing synchronously?

  8. ketang commented on Jun 13, 2022

    @ketang
    Contributor

    I want us to have a product that has a really low floor for the initial step, and an increasingly high ceiling on its power. But I also want, um, ladders and escalators to help customers climb higher. The more we do for the customer, the better, all else being equal.

    Goal right now? Totally on board with optimizing for getting started. Goal in 2023? Maximum power at minimum customer effort. I think there are smart things we can do with template composition like what Ben described (but not only what Ben described):

    A "meta template" or GUI-based configuration wizard that creates a template and spits out the source would eventually be necessary for people who don't want to write Terraform.

    I think it's also important for us to take on more of this because we will be supporting more provisioning technologies than just Terraform, and we want them all to have as many capabilities built in as possible.

  9. tjcran commented on Jun 13, 2022

    @tjcran

    I'd propose for OSS launch:

    • optimized for "getting started" and a clean and working out of the box set-up for as many of our templates as we can do.
    • "recommended" label on the docker-compose template and bumped to top of list
    • code-server inclusion add code-server to all our quickstart templates #2193 in as many as it makes sense.
    • rdp/vnc Access the desktop environment of a workspace #2106 for as many as it makes sense
    • Now I wonder if we could do code-server and rdp/vnc as input variables on all our templates so when user creates workspace they can check a box to say if they want code-server and/or a desktop experience or not... that way they CAN do that, but they don't HAVE to do that.

    post-launch: gui wizard that's terraform agnostic and ez-mode for people that don't want to or can't do terraform

  10. spikecurtis commented on Jun 14, 2022

    @spikecurtis
    CollaboratorAuthor

    Unfortunately I'm finding the language around optimizing for "getting started" a little too ambiguous, given the points of disagreement. That is to say, I don't know whether we have rallied around a powerful, fully-featured initial experience with the templates, or if people are still advocating for more stripped down templates as a "base" for people to build from?

  11. tjcran commented on Jun 14, 2022

    @tjcran

    Unfortunately I'm finding the language around optimizing for "getting started" a little too ambiguous, given the points of disagreement. That is to say, I don't know whether we have rallied around a powerful, fully-featured initial experience with the templates, or if people are still advocating for more stripped down templates as a "base" for people to build from?

    After this discussion, I'd suggest a powerful, fully-featured initial experience as our near-term target.

  12. misskniss commented on Jun 14, 2022

    @misskniss

    Moved this epic into the sprint. Goal: Groomed issues and decisions made so we can execute.

  13. ketang commented on Jun 14, 2022

    @ketang
    Contributor

    After this discussion, I'd suggest a powerful, fully-featured initial experience as our near-term target.

    Ha! I was thinking something different but maybe not that different. Forgot to hit the button before taking off from Venice.

    I'll take a stab at it.

    Getting started minimum out-of-the-box functionality:

    • you can run a web terminal
    • you can ssh to the workspace
    • code-server is installed
    • you can install arbitrary additional software from the command line

    Beyond scope

    • JetBrains IDE installation/integration
    • Custom VPCs

    Uhhh. Maybe some other stuff that v1 does?

    Support this on:

    • Local machine
    • containers set up viadocker-compose
    • GKE
    • GCP VM
    • AWS VM
    • Azure VM
    • DigitalOcean
    • Standalone Kubernetes
    • Maybe Azure AKS
  14. tjcran commented on Jun 15, 2022

    @tjcran

    @spikecurtis and I had a good chat on this and Spike had a good suggestion that I'll attempt to elaborate on here.


    The idea Spike had is that we basically have two distinct "style" of template.

    1. Quick-start - dotfiles, VNC/RDP, code-server etc and ready to work out of the box. This is what will live in the basic directory in the repo that includes examples.
    2. Base template - bare bones and not expected to work out of the box. Expected to be slightly or even heavily modified. Our docs will provide how-tos on how-to modify, adapt, and generally use. Maybe we keep these elsewhere in the repo or in a different repo?

    Both of these categories will also exist for the major cloud providers+Docker, but not any cloud provider under the sun.

    • AWS
    • GCP
    • Azure
    • DigitalOcean
    • Docker

    Finally, we'll include code-server in the "quick-start" templates, but rather than providing templates with every IDE out there and, we just provide docs on how to add major IDEs into your workspace.

  15. misskniss commented on Jun 15, 2022

    @misskniss

    I am in agreement with the approach proposed above by Spike and Tyler. This would likely match the expectations and desires of businesses and users looking to evaluate or getting started with a permanent deployment. We should be intentional and considered in the approach here since it is a core differentiator for us.

  16. ketang commented on Jun 15, 2022

    @ketang
    Contributor

    I strongly disagree with shipping something that requires user changes to work, especially for the key infrastructure providers listed above. You should be able to get workspaces running on reasonably configured e.g. GCP VMs without editing any Terraform.

  17. tjcran commented on Jun 15, 2022

    @tjcran

    I strongly disagree with shipping something that requires user changes to work, especially for the key infrastructure providers listed above. You should be able to get workspaces running on reasonably configured e.g. GCP VMs without editing any Terraform.

    The proposal includes a set of templates that are fully featured that work out of the box for every major provider.

  18. ketang commented on Jun 15, 2022

    @ketang
    Contributor

    What would we be shipping that leaves exercises for the user?

  19. added this to the Enterprise MVP milestone on Jun 16, 2022
  20. spikecurtis commented on Jun 16, 2022

    @spikecurtis
    CollaboratorAuthor

    Yeah, I think every template example should be working out of the box. The base ones are just... basic, and don't include anything that we're not sure nearly everyone will want (e.g. compute with an agent, persistent volume). These would be a starting place for people to build up their own custom template.

  21. tjcran commented on Jun 16, 2022

    @tjcran

    Update: I shared the following proposal for our templates strategy with @ketang @bpmct @ammario @kylecarbs @misskniss to have two sets of templates, of which BOTH sets will work out of the box. There was agreement on this approach. This will prevent us from having a long-tail of templates to support.

    In addition, our docs need to be improved to teach users how to make templates, modify templates, add IDEs, and use dotfiles.

    The issues in this epic should reflect and align with this proposed strategy.

    Re-stating the proposal:

    1. "quick-start" templates that have code-server, vnc/rdp, etc and will provide the basic "good" experience many people will want.
    2. basic building block templates.

    For each of these options:

  22. ammario commented on Jun 21, 2022

    @ammario
    Member

    I agree with the Quickstarts for each cloud. (cc @bpmct)

    We've made good progress on the IDE, Dotfiles, and templates docs. I think cloud-specific Quickstarts is the highest leverage next thing for us.

  23. removed this from the Enterprise MVP milestone on Jul 22, 2022
  24. kylecarbs commented on Aug 24, 2022

    @kylecarbs
    Member

    I'm going to close this for now. I think it's important that we continually evolve our example templates, but they seem in an OK spot for now.

    Let's await feedback to make more changes!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions