Skip to content

Commit 7f96928

Browse files
FabianKrammFabianKramm
committed
Enhance docs
1 parent b0b6760 commit 7f96928

5 files changed

Lines changed: 47 additions & 18 deletions

File tree

‎docs/docs/getting-started/advantages.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: 4. Why use DevSpace during development?
3+
---
4+
5+
# Why use DevSpace for development
6+
The basic idea behind DevSpace is to bring the different software execution environments during development, staging, testing and production closer together. One issue with current cloud-native application development is that the development environment where code is actually written often greatly differs from the environment where it is deployed to. In bigger software teams, development execution environments often even differ from each other, which can lead to numerous problems and inefficiencies during development and the eventual execution.
7+
8+
One solution to this problem is to use kubernetes not only during the later stages of the software development process, but instead from the beginning on. This has the advantage that the developer can continuously test during development how the application will run, scale and behave in a kubernetes environment. Furthermore the execution environment can be simply shared with other developers in the team through the kubernetes .yaml files. We believe that this approach would lead to ultimately better cloud-native applications.
9+
10+
However, while this idea sounds tempting, using kubernetes during development currently is a real pain for a developer. Kubernetes clusters are not easy to configure, many features require deep knowledge of kubernetes and it is not easy to develop code in remote containers without redeploying after every change. The ambition of DevSpace is to facilitate and speed up development with kubernetes and keep the actual workflow of the developer as close as possible to the previous local development workflow.
11+
12+
# How is it different to other kubernetes development tools
13+
There are already several other tools that facilitate the continuous development of kubernetes applications. While these tools are a good beginning, they unfortunately in our opinion don't provide a real local coding experience and have several drawbacks.
14+
15+
## draft & skaffold
16+
Draft and skaffold facilitate continuous development for kubernetes applications. They support the workflow for building, pushing and deploying the application. While they automate and abstract some complexity during building and deploying applications, the problem with these tools is in our opinion that continuous development is tedious, because after each code change a new pipeline with image building and deploying is started. Our approach let's the developer exchange the files that changed directly in the target container without the need to redeploy after every change.
17+
18+
## telepresence
19+
Telepresence substitutes a two-way network proxy for your normal pod running in the Kubernetes cluster. This pod proxies data from your Kubernetes environment to the local process. The local process has its networking transparently overridden so that DNS calls and TCP connections are routed through the proxy to the remote Kubernetes cluster. While this sounds great at first, the approach has several drawbacks: accessing localhost in the container refers to the local machine and not the pod ip, volumes only work with code changes and there is no windows support.
20+
21+
## ksync

‎docs/docs/getting-started/cleanup.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: 4. Cleanup
2+
title: 4. Removing DevSpace
33
---
44

55
## devspace down

‎docs/docs/getting-started/coding.md‎

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,33 @@
11
---
2-
title: 3. Coding with your DevSpace
2+
title: 3. Coding with DevSpace
33
---
44

5-
Coding within your Devspace is as easy as coding on localhost.
5+
There are 5 central features the devspace cli is doing for you when running `devspace up`:
6+
1. Image building
7+
2. Helm chart deployment
8+
3. Port forwarding from local machine to remote containers
9+
4. File synchronization between local machine and remote containers
10+
5. Terminal access to your release pods
611

7-
## Terminal Access
8-
Running `devspace up` will open a terminal for you, so you can directly run commands within your DevSpace. By default, `devspace up` will use `bash` as shell and fall-back to `sh` if `bash` is not available within your container.
12+
## Image Building
13+
When you run `devspace up` for the first time, your [/Dockerfile](/docs/configuration/dockerfile.html) will be built automatically. If you run `devspace up` again, it will check if the [/Dockerfile](/docs/configuration/dockerfile.html) has been modified since the last build and only re-build if the [/Dockerfile](/docs/configuration/dockerfile.html) has changed since then.
914

10-
**Note:** Use `devspace up -s /my/shell` to open the terminal with a different shell.
15+
**Note:** To force re-build your docker image, you can run `devspace up -b`.
1116

12-
## Port Forwarding
13-
By default, `devspace up` will forward all TCP and UDP traffic on the ports your application listens on from your localhost machine to the DevSpace within your cluster.
17+
## Chart Deployment
18+
The devspace cli will deploy a helm chart in the target cluster by running `devspace up`. The deployed chart can be found locally in the `chart/` folder and can be changed as wanted. There is one special field in the `chart/values.yaml`: For each container specified under the key `containers.containerName`, the `image` property will be filled automatically after the build step.
1419

15-
**Note:** See [/.devspace/config.yaml configuration](/docs/configuration/config.yaml.html) for details on how to configure more advanced port forwarding procedures.
20+
If you are interested how helm charts work and how to write and adjust them, you can take a look at [helm charts](https://github.com/helm/helm/blob/master/docs/charts.md)
1621

17-
## Code Synchronization & Hot Reloading
18-
By default, `devspace up` will automatically synchronize your source code to the `/app` folder within your DevSpace. This sync-procedure is bi-directional and allows you to use hot reloading (e.g. for using nodemon for nodejs).
22+
## Terminal Access
23+
Running `devspace up` will by default open a terminal for you, so you can directly run commands within your DevSpace. By default, `devspace up` will use `bash` as shell and fall-back to `sh` if `bash` is not available within your container. If you wish to run a different shell or command just execute `devspace up [your command or shell]`
1924

20-
**Note:** See [/.devspace/config.yaml configuration](/docs/configuration/config.yaml.html) for details on how to configure more advanced code synchronization procedures.
25+
By running `devspace up` the cli will automatically establish the port forwarding and sync mechanism specified in the [/.devspace/config.yaml](/docs/configuration/config.yaml.html). If you just want to access the release pod, you can also execute `devspace enter` or `devspace enter [command]`.
2126

22-
## Image Building
23-
When you run `devspace up` for the first time, your [/Dockerfile](/docs/configuration/dockerfile.html) will be built automatically. If you run `devspace up` again, it will check if the [/Dockerfile](/docs/configuration/dockerfile.html) has been modified since the last build and only re-build if the [/Dockerfile](/docs/configuration/dockerfile.html) has changed since then.
27+
## Port Forwarding
28+
By default, `devspace up` will forward all TCP and UDP traffic on the ports your application listens to from your localhost machine to the DevSpace within your cluster. You can see the configured ports by running `devspace list port`. If you want to add a port just run `devspace add port 8080` and on the next `devspace up` the port 8080 will be forwarded from your local machine to the remote port.
2429

25-
**Note:** To force re-build your docker image, you can run `devspace up -b`.
30+
**Note:** See [/.devspace/config.yaml](/docs/configuration/config.yaml.html) for details on how to configure more advanced port forwarding procedures.
31+
32+
## Code Synchronization & Hot Reloading
33+
By default a file synchronization path is configured from the project path to the release pod container path `/app`. `devspace up` will then automatically synchronize your source code and remote changes. This allows you to use hot reloading (e.g. for using nodemon for nodejs). You can change this behaviour as you want by configuring the paths in the [/.devspace/config.yaml](/docs/configuration/config.yaml.html)

‎docs/docs/getting-started/quickstart.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ You can easily setup a DevSpace for any existing project. This quickstart guide
88
3. [Coding with your DevSpace](/docs/getting-started/coding)
99
4. [Cleanup](/docs/getting-started/cleanup) (optional)
1010

11-
1211
## Prerequiste: A Kubernetes Cluster (e.g. Minikube)
1312
To get started, you need a Kubernetes cluster. If you do not have one yet, check out our **[Kubernetes Installation Guide](/docs/advanced/kubernetes)**.
1413

‎docs/docs/getting-started/start.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ devspace up
1010
This command will:
1111
1. ask some basic configuration questions,
1212
2. create a Dockerfile, a helm chart and the devspace config (see below),
13-
3. start a Tiller server and a private Docker registry in your Kubernetes cluster,
13+
3. start a Tiller server (if necessary) and a private Docker registry (if wanted, you can also use any other registry) in your Kubernetes cluster,
1414
4. build your Dockerfile and deploy the helm chart in chart/,
1515
5. start port-forwarding and real-time code synchronization,
1616
6. and open a terminal session.
@@ -34,5 +34,6 @@ YOUR_PROJECT_PATH/
3434
| |-- .gitignore
3535
| |-- cluster.yaml
3636
| |-- config.yaml
37-
```
37+
```
38+
3839
**Note:** Don't worry, you can simply run `devspace reset` to reset your project to its original state (see [Cleanup](/docs/getting-started/cleanup.html)).

0 commit comments

Comments
 (0)