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
Copy file name to clipboardExpand all lines: docs/running-locally.md
+24-35Lines changed: 24 additions & 35 deletions
Original file line number
Diff line number
Diff line change
@@ -1,53 +1,33 @@
1
1
# Running Locally
2
2
3
-
You have two options:
3
+
## Development Environment Setup
4
4
5
-
1. Use the [Dev Container](#development-container). This takes about 7 minutes. This can be used with VSCode, the `devcontainer` CLI, or GitHub Codespaces.
6
-
1. Install the [requirements](#requirements) on your computer manually. This takes about 1 hour.
5
+
You have two options for setting up your development environment:
7
6
8
-
## Development Container
7
+
1. Use the [Dev Container](#development-container), either locally or via [GitHub Codespaces](https://github.com/codespaces). This is usually the fastest and easiest way to get started.
8
+
1.[Manual installation](#manual-installation) of the necessary tooling. This requires a basic understanding of administering Kubernetes and package management for your OS.
9
9
10
-
The development container should be able to do everything you need to do to develop Argo Workflows without installing tools on your local machine. It takes quite a long time to build the container. It runs `k3d` inside the container so you have a cluster to test against. To communicate with services running either in other development containers or directly on the local machine (e.g. a database), the following URL can be used in the workflow spec: `host.docker.internal:<PORT>`. This facilitates the implementation of workflows which need to connect to a database or an API server.
10
+
### Initial Local Setup
11
+
12
+
Unless you're using GitHub Codespaces, the first step is cloning the Git repo into `$GOPATH/src/github.com/argoproj/argo-workflows`. Any other path will break the code generation.
13
+
14
+
### Development Container
15
+
16
+
Prebuilt [development container](https://containers.dev/) images are provided for both `amd64` and `arm64` containing all you need to develop Argo Workflows, without installing tools on your local machine. Provisioning a dev container is fully automated and typically takes ~1 minute.
11
17
12
18
You can use the development container in a few different ways:
13
19
14
20
1.[Visual Studio Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Open your `argo-workflows` folder in VSCode and it should offer to use the development container automatically. VSCode will allow you to forward ports to allow your external browser to access the running components.
15
-
1.[`devcontainer` CLI](https://github.com/devcontainers/cli). Once installed, go to your `argo-workflows` folder and run `devcontainer up --workspace-folder .` followed by`devcontainer exec --workspace-folder . /bin/bash` to get a shell where you can build the code. You can use any editor outside the container to edit code; any changes will be mirrored inside the container. Due to a limitation of the CLI, only port 8080 (the Web UI) will be exposed for you to access if you run this way. Other services are usable from the shell inside.
21
+
1.[`devcontainer` CLI](https://github.com/devcontainers/cli). In your `argo-workflows` folder, run `make devcontainer-up`, which will automatically install the CLI and start the container. Then, use`devcontainer exec --workspace-folder . /bin/bash` to get a shell where you can build the code. You can use any editor outside the container to edit code; any changes will be mirrored inside the container. Due to a limitation of the CLI, only port 8080 (the Web UI) will be exposed for you to access if you run this way. Other services are usable from the shell inside.
16
22
1.[GitHub Codespaces](https://github.com/codespaces). You can start editing as soon as VSCode is open, though you may want to wait for `pre-build.sh` to finish installing dependencies, building binaries, and setting up the cluster before running any commands in the terminal. Once you start running services (see next steps below), you can click on the "PORTS" tab in the VSCode terminal to see all forwarded ports. You can open the Web UI in a new tab from there.
17
23
18
24
Once you have entered the container, continue to [Developing Locally](#developing-locally).
19
25
20
-
Note:
21
-
22
-
* for **Apple Silicon**
23
-
* This platform can spend 3 times the indicated time
24
-
* Configure Docker Desktop to use BuildKit:
25
-
26
-
```json
27
-
"features": {
28
-
"buildkit": true
29
-
},
30
-
```
31
-
32
-
* For **Windows WSL2**
33
-
* Configure [`.wslconfig`](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to limit memory usage by the WSL2 to prevent VSCode OOM.
34
-
35
-
* For **Linux**
36
-
* Use [Docker Desktop](https://docs.docker.com/desktop/linux/install/) instead of [Docker Engine](https://docs.docker.com/engine/install/) to prevent incorrect network configuration by k3d.
37
-
38
-
## Requirements
26
+
The container runs [k3d](https://k3d.io/) via [docker-in-docker](https://github.com/devcontainers/features/tree/main/src/docker-in-docker) so you have a cluster to test against. To communicate with services running either in other development containers or directly on the local machine (e.g. a database), the following URL can be used in the workflow spec: `host.docker.internal:<PORT>`. This facilitates the implementation of workflows which need to connect to a database or an API server.
39
27
40
-
Clone the Git repo into: `$GOPATH/src/github.com/argoproj/argo-workflows`. Any other path will break the code generation.
28
+
Note for Windows: configure [`.wslconfig`](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to limit memory usage by the WSL2 to prevent VSCode OOM.
41
29
42
-
Add the following to your `/etc/hosts`:
43
-
44
-
```text
45
-
127.0.0.1 dex
46
-
127.0.0.1 minio
47
-
127.0.0.1 postgres
48
-
127.0.0.1 mysql
49
-
127.0.0.1 azurite
50
-
```
30
+
### Manual Installation
51
31
52
32
To build on your own machine without using the Dev Container you will need:
53
33
@@ -57,6 +37,15 @@ To build on your own machine without using the Dev Container you will need:
*[`node`](https://nodejs.org/download/release/latest-v16.x/) for running the UI
59
39
* A local Kubernetes cluster ([`k3d`](https://k3d.io/), [`kind`](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), or [`minikube`](https://minikube.sigs.k8s.io/docs/start/))
40
+
* The following entries in your `/etc/hosts` file:
41
+
42
+
```text
43
+
127.0.0.1 dex
44
+
127.0.0.1 minio
45
+
127.0.0.1 postgres
46
+
127.0.0.1 mysql
47
+
127.0.0.1 azurite
48
+
```
60
49
61
50
We recommend using [K3D](https://k3d.io/) to set up the local Kubernetes cluster since this will allow you to test RBAC
62
51
set-up and is fast. You can set-up K3D to be part of your default kube config as follows:
0 commit comments