You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
@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).
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)
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.
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.
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
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?
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.
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
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?
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.
@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.
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.
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.
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.
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.
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.
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.
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:
"quick-start" templates that have code-server, vnc/rdp, etc and will provide the basic "good" experience many people will want.
Activity
spikecurtis commentedon Jun 13, 2022
@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:
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
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 sizesis 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.tjcran commentedon Jun 13, 2022
@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).
tjcran commentedon Jun 13, 2022
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-serverin most of the examples. (maybe have a jetbrains example template too which doesn't have code-server)kylecarbs commentedon Jun 13, 2022
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.
bpmct commentedon Jun 13, 2022
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.
tjcran commentedon Jun 13, 2022
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:
I also am aligned with these points:
spikecurtis commentedon Jun 13, 2022
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?
ketang commentedon Jun 13, 2022
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):
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.
tjcran commentedon Jun 13, 2022
I'd propose for OSS launch:
code-serverand 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
spikecurtis commentedon Jun 14, 2022
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?
tjcran commentedon Jun 14, 2022
After this discussion, I'd suggest a powerful, fully-featured initial experience as our near-term target.
misskniss commentedon Jun 14, 2022
Moved this epic into the sprint. Goal: Groomed issues and decisions made so we can execute.
ketang commentedon Jun 14, 2022
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:
Beyond scope
Uhhh. Maybe some other stuff that v1 does?
Support this on:
docker-composetjcran commentedon Jun 15, 2022
@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.
Both of these categories will also exist for the major cloud providers+Docker, but not any cloud provider under the sun.
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.
misskniss commentedon Jun 15, 2022
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.
ketang commentedon Jun 15, 2022
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.
tjcran commentedon Jun 15, 2022
The proposal includes a set of templates that are fully featured that work out of the box for every major provider.
ketang commentedon Jun 15, 2022
What would we be shipping that leaves exercises for the user?
spikecurtis commentedon Jun 16, 2022
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.
tjcran commentedon Jun 16, 2022
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:
For each of these options:
ammario commentedon Jun 21, 2022
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.
kylecarbs commentedon Aug 24, 2022
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!