This repository has been archived on 2024-04-08. You can view files and clone it, but cannot push or open issues or pull requests.
dagger/docs/learn/101-use.md
Sam Alba a8889d69fc docs: 101: fixed init command
Signed-off-by: Sam Alba <sam.alba@gmail.com>
2021-06-17 17:49:16 +02:00

4.4 KiB

slug
/learn/101-basics

Dagger 101: basic usage

In this guide, you will learn the basics of Dagger by interacting with a pre-configured environment. Then you will move on to creating your own environment from scratch.

Our pre-configured environment deploys a simple React application to a special hosting environment created and managed by us, the Dagger team, for the purpose of this tutorial. This will allow you to deploy something "real" right away, without having to configure your own infrastructure first.

In later guides, you will learn how to configure Dagger to deploy to your own infrastructure. And, for advanced users, how to share access to your infrastructure in the same way that we are sharing access to ours now.

Initial setup

Install Dagger

First, make sure you have installed dagger on your local machine.

Setup example app

You will need a local copy of the Dagger examples repository. NOTE: you may use the same local copy across all tutorials.

git clone https://github.com/dagger/examples

Make sure that all commands are run from the todoapp directory:

cd examples/todoapp

Import the tutorial key

Dagger natively supports encrypted secrets: when a user inputs a value marked as secret (for example a password, API token or ssh key) it is automatically encrypted with that user's key, and no other user can access that value unless they are explicitly given access.

In the interest of security, Dagger has no way not to encrypt a secret value. But this causes a dilemma for this tutorial: how do we give unrestricted public access to our (carefully sandboxed) infrastructure, so that anyone can deploy to it?

To solve this dilemma, we included the private key used to encrypt the tutorial's secret inputs. Simply import the key to your Dagger installation, and you're good to go:

./import-tutorial-key.sh

First deployment

Now that your environment is setup, you are ready to deploy:

dagger up

That's it! You have just made your first deployment with Dagger.

The URL of your newly deployed app should be visible towards the end of the command output. If you visit that URL, you should see your application live!

Code, deploy, repeat

This environment is pre-configured to deploy from the ./todoapp directory, so you can make any change you want to that directory, then deploy it with dagger up. You can even replace our example React code with any React application!

NOTE: you don't have to commit your changes to the git repository before deploying them.

Under the hood

This example showed you how to deploy and develop on an application that is already configured with dagger. Now, let's learn a few concepts to help you understand how this was put together.

The Environment

An Environment holds the entire deployment configuration.

You can list existing environment from the ./todoapp directory:

dagger list

You should see an environment named s3. You can have many environments within your app. For instance one for staging, one for dev, etc...

Each environment can have different kind of deployment code. For example, a dev environment can deploy locally, a staging environment can deploy to a remote infrastructure, and so on.

The plan

The plan is the deployment code, that includes the logic to deploy the local application to an AWS S3 bucket. From the todoapp directory, you can list the code of the plan:

ls -l .dagger/env/s3/plan/

Any code change to the plan will be applied during the next dagger up.

The inputs

The plan can define one or several inputs in order to take some information from the user. Here is how to list the current inputs:

dagger input list

The inputs are persisted inside the .dagger directory and pushed to your git repository. That's why this example application worked out of the box.

The outputs

The plan defines one or several outputs. They can show useful information at the end of the deployment. That's how we read the deploy url at the end of the deployment. Here is the command to list all inputs:

dagger output list

What's next?

At this point, you have deployed your first application using dagger and learned some dagger commands. You are now ready to learn more about how to program dagger.