Skip to content

feat: Update README with highlights and getting started guide #627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 28, 2022
Merged

feat: Update README with highlights and getting started guide #627

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cee8256
feat: Update README with highlights and getting started guide
kylecarbs Mar 28, 2022
747cdf4
Merge branch 'main' into contributing
kylecarbs Mar 28, 2022
aadf806
Merge branch 'main' into contributing
kylecarbs Mar 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,10 @@ install: bin
@echo "-- CLI available at $(shell ls $(INSTALL_DIR)/coder*)"
.PHONY: install

lint:
golangci-lint run
.PHONY: lint

peerbroker/proto: peerbroker/proto/peerbroker.proto
protoc \
--go_out=. \
Expand Down Expand Up @@ -89,6 +93,6 @@ site/out:
git checkout HEAD site/out
.PHONY: site/out

lint:
golangci-lint run
.PHONY: lint
test:
gotestsum -- -v -short ./...

103 changes: 43 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,64 @@
[![coder](https://github.com/coder/coder/actions/workflows/coder.yaml/badge.svg)](https://github.com/coder/coder/actions/workflows/coder.yaml)
[![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)
# Coder

# Coder v2
[!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/coder/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder)

This repository contains source code for Coder V2. Additional documentation:
Provision remote development environments with Terraform.

- [Workspaces V2 RFC](https://www.notion.so/coderhq/b48040da8bfe46eca1f32749b69420dd?v=a4e7d23495094644b939b08caba8e381&p=e908a8cd54804ddd910367abf03c8d0a)
## Highlights

## Directory Structure
- Automate development environments for Linux, Windows, and MacOS in your cloud
- Start writing code with a single command
- Use one of many [examples](./examples) to get started
Comment on lines +9 to +11
Copy link
Member

@bpmct bpmct Mar 28, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was gonna nit on the messaging a bit, but decided it'd be more productive once we create a messaging doc. I like the placement of these here 👍🏼

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, we can totally change these whenever. Feel free to nit on em' now if you'd like. I'm all ears!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can make these a lot more compelling but I'll wait to invest until Ben takes a pass.


- `.github/`: Settings for [Dependabot for updating dependencies](https://docs.github.com/en/code-security/supply-chain-security/customizing-dependency-updates) and [build/deploy pipelines with GitHub Actions](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions).
- [`semantic.yaml`](./github/semantic.yaml): Configuration for [semantic pull requests](https://github.com/apps/semantic-pull-requests)
- `examples`: Example terraform project templates.
- `site`: Front-end UI code.
## Getting Started

## Development

### Pre-requisites

- `git`
- `go` version 1.17, with the `GOPATH` environment variable set
- `node`
- `yarn`

### Cloning

- `git clone https://github.com/coder/coder`
- `cd coder`

### Building

- `make build`
- `make install`
Install [the latest release](https://github.com/coder/coder/releases).

The `coder` CLI binary will now be available at `$GOPATH/bin/coder`
To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit):

### Running
```bash
$ coder start --dev
```

After building, the binaries will be available at:
- `dist/coder_{os}_{arch}/coder`
To run a production deployment with PostgreSQL:

For the purpose of these steps, an OS of `linux` and an arch of `amd64` is assumed.
```bash
$ CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<password>" \
coder start
```

To manually run the server and go through first-time set up, run the following commands in separate terminals:
- `dist/coder_linux_amd64/coder daemon` <-- starts the Coder server on port 3000
- `dist/coder_linux_amd64/coder login http://localhost:3000` <-- runs through first-time setup, creating a user and org
To run as a system service, install with `.deb` or `.rpm`:

You'll now be able to login and access the server.
```bash
# Edit the configuration!
$ sudo vim /etc/coder.d/coder.env
$ sudo service coder restart
```

- `dist/coder_linux_amd64/coder projects create -d /path/to/project`
### Your First Workspace

### Development
In a new terminal, create a new project (eg. Develop in Linux on Google Cloud):

- `./develop.sh`
```
$ coder projects init
$ coder projects create
```

The `develop.sh` script does three things:
Create a new workspace and SSH in:

- runs `coder daemon` locally on port `3000`
- runs `webpack-dev-server` on port `8080`
- sets up an initial user and organization
```
$ coder workspaces create my-first-workspace
$ coder ssh my-first-workspace
```

This is the recommend flow for working on the front-end, as hot-reload is set up as part of the webpack config.

Note that `./develop.sh` creates a user and allows you to log into the UI, but does not log you into the CLI, which is required for creating a project. Use the `login` command above before the `projects create` command.

While we're working on automating XState typegen, you may need to run `yarn typegen` from `site`.

## Front-End Plan

For the front-end team, we're planning on 2 phases to the 'v2' work:

### Phase 1

Phase 1 is the 'new-wine-in-an-old-bottle' approach - we want to preserve the look and feel (UX) of v1, while testing and validating the market fit of our new v2 provisioner model. This means that we'll preserve Material UI and re-use components from v1 (porting them over to the v2 codebase).
## Development

### Phase 2
The code structure is inspired by [Basics of Unix Philosophy](https://homepage.cs.uri.edu/~thenry/resources/unix_art/ch01s06.html) and [Effective Go](https://go.dev/doc/effective_go).

Phase 2 is the 'new-wine-in-a-new-bottle' - which we can do once we've successfully packaged the new wine in the old bottle.
Coder requires Go 1.18+, Node 14+, and GNU Make.

In other words, once we've validated that the new strategy fits and is desirable for our customers, we'd like to build a new, v2-native UI (leveraging designers on the team to build a first-class experience around the new provisioner model).
- `make bin` builds binaries
- `make install` installs binaries to `$GOPATH/bin`
- `make test`
- `make release` dry-runs a new release
- `./develop.sh` hot-reloads for frontend development