How to use DevSpace with APPUiO Cloud

DevSpace is an open-source developer tool for Kubernetes that lets you develop and deploy cloud-native software faster.

This page will describe the required steps to use DevSpace successfully with APPUiO Cloud.

This information is provided as a courtesy for APPUiO Cloud users. We don’t provide support for DevSpace, and in case of issues, you are invited to contact the developers of DevSpace at their GitHub project.

Requirements

To follow this guide, please make sure that you have the following tools installed:

devspace: The DevSpace documentation explains how to install it in your operating system of choice.
oc: You can download the OpenShift command directly from APPUiO Cloud, selecting the help menu (marked as a question mark) and selecting the "Command line tools" entry.

Procedure

This section explains the steps required to use DevSpace with APPUiO Cloud.

1. Login to APPUiO Cloud

Follow these steps to login to APPUiO Cloud on your terminal:

oc login --server=https://api.${zone}.appuio.cloud:6443

You can find the exact URL of your chosen zone in the APPUiO Cloud Portal.

This command displays a URL on your terminal:

You must obtain an API token by visiting
https://oauth-openshift.apps.${zone}.appuio.cloud/oauth/token/request

Click on the link above and open it in your browser.
Click "Display token" and copy the login command shown as "Log in with this token"

Paste the oc login command on the terminal:

oc login --token=sha256~_xxxxxx_xxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxx-X \
    --server=https://api.${zone}.appuio.cloud:6443

Create a new project called "[YOUR_USERNAME]-devspace"
```
oc new-project [YOUR_USERNAME]-devspace
```

2. Login to the APPUiO Cloud Container Registry

DevSpace uses Docker to build the container image, and to publish to a container registry. In this example we’re going to use the APPUiO Cloud integrated container registry.

oc whoami -t | docker login registry.${zone}.appuio.cloud -u $(oc whoami) --password-stdin

3. Clone the sample "Fortune in Go" project

The "Fortune in Go" project provides a very simple Go application to start with. You can clone it from GitLab:

git clone https://gitlab.com/vshn/applications/fortune-go.git

And then cd into it:

cd fortune-go

4. Setup DevSpace

Initialize DevSpace in the current project running this command:
```
devspace init
```
This generates a new file in your project called devspace.yaml. When prompted, select the following options:
1. How do you want to deploy this project?
  - helm: Use Component Helm Chart [QUICKSTART] (devspace.sh/component-chart/docs)
2. How should DevSpace build the container image for this project?
  - Based on this existing Dockerfile: ./Dockerfile
3. Which registry would you want to use to push images to?
  - Use other registry
4. Please provide the registry hostname without the image path
  - registry.[YOUR_CHOSEN_ZONE].appuio.cloud
    
    Remember to login to your APPUiO Cloud container registry first! Please refer the previous step in this guide for details.
Notify DevSpace of your working project in APPUiO Cloud.
```
devspace use namespace [YOUR_USERNAME]-devspace
```

5. Customize the `devspace.yaml` file

DevSpace works by synchronizing your local work directory with a running pod on APPUiO Cloud; this requires write permissions in pods, but by default, APPUiO Cloud prevents such operations. You must therefore modify the devspace.yaml file in the root of your project as follows.

At the top of the file, change the value of the IMAGE variable from this:
```
vars:
- name: IMAGE
  value: registry.[YOUR_CHOSEN_ZONE].appuio.cloud/[YOUR_USERNAME]/project/app
```
to this:
```
vars:
- name: IMAGE
  value: registry.[YOUR_CHOSEN_ZONE].appuio.cloud/[YOUR_USERNAME]-devspace/app
```
Remember to customize the parts marked as [YOUR_USERNAME] and [YOUR_CHOSEN_ZONE] to your liking (and according to the Zones documentation page).

Then change the dev:replacePods:replaceImage value, from:

dev:
  # ...
  replacePods:
  - imageSelector: ${IMAGE}
    replaceImage: loftsh/go:latest

to:

dev:
  # ...
  replacePods:
  - imageSelector: ${IMAGE}
    replaceImage: registry.gitlab.com/vshn/demos/demo-devspace-custom-image:latest (1)

1	This container image (together with its `Dockerfile`) is available at the DevSpace in APPUiO Base Image project.

6. Launch DevSpace

Launch DevSpace on the terminal:

devspace dev

DevSpace deploys your container to the cluster and gives you a terminal prompt; run the go run main.go command, and watch your application in action in localhost:8080.

Now you can edit any file in your project, and as soon as you save it, DevSpace will automatically sync your files with the pod, increasing your productivity. Just stop the web server with CTRL+C, and start it again to see your changes.

Once you’re done developing your application, use the following command to deploy it in production:

devspace deploy -p production

You can see it in production either by adding an Ingress object, or by using the following command:

devspace open

and selecting the "via localhost" option. If you would like to clean your APPUiO Cloud project from all DevSpace products, just use this:

devspace purge

Tips & Tricks

Here go some ideas to use DevSpace efficiently:

You can provide a different image in the dev:replacePods:replaceImage field, including all of the dependencies required by your application. The DevSpace in APPUiO Base Image example can serve as a starting point.
DevSpace has plenty of options to configure the devspace.yaml file. Check the DevSpace configuration reference to learn more.
Help your team adopt DevSpace by adding the appropriate information in your project’s README file.