script deploy plugged to docGenerator repo + rename doc/ to docs/

Signed-off-by: slumbering <slumbering.pierrot@gmail.com>
2021-05-21 17:20:15 +02:00
parent 49176b9976
commit 828f9d9ff1
7 changed files with 101 additions and 29 deletions
--- a/docs/01_overview.md
+++ b/docs/01_overview.md
@@ -0,0 +1,41 @@
+# Dagger
+
+Dagger is a programmable deployment system.
+
+Using Dagger, software builders can automate the deployment of any application to any infrastructure,
+in just a few lines of code.
+
+![image](https://user-images.githubusercontent.com/29565/112705398-d0222980-8e5b-11eb-98b9-32c117a3d606.jpeg)
+
+The Dagger platform adapts to your application, not the other way around.
+Thanks to its ecosystem of reusable packages and flexible scripting system, Dagger can be dropped
+into any software project without requiring changes to its architecture or workflow.
+Think of it as your "devops superglu".
+
+No matter how your deployment works under the hood, you can manage it with the same Dagger user interface.
+This makes developers more productive, because they don't have to learn a new workflow every time their deployment
+system changes.
+
+## Learn More
+
+* [Dagger vs. Other Software](doc/vs)
+* [Dagger Programming Guide](doc/programming)
+* [Dagger Operator Manual](doc/operator)
+
+
+## Download and Install
+
+* [Install Dagger from source](doc/install)
+* Binary distributions [*coming soon*]
+
+## Community
+
+Join the [Dagger community chatroom](https://discord.gg/Rmffpmc) on Discord.
+We welcome beginners and experts alike!
+
+
+## Alpha disclaimer
+
+Dagger is *alpha-quality software*. It has many bugs, the user interface is minimal, and it may change in incompatible ways at any time. If you are still willing to try it, thank you! We appreciate your help and encourage you to ask questions and report issues.
+
+
--- a/docs/install.md
+++ b/docs/install.md
@@ -0,0 +1,76 @@
+# Installing or upgrading Dagger
+
+## Summary
+
+- [Installing or upgrading Dagger](#installing-or-upgrading-dagger)
+  - [Summary](#summary)
+  - [Option 1 (Mac OS only): install or upgrade from Homebrew](#option-1-mac-os-only-install-or-upgrade-from-homebrew)
+  - [Option 2: install or upgrade from a shell script](#option-2-install-or-upgrade-from-a-shell-script)
+  - [Option 3: Manually fetch the latest binary release from Github](#option-3-manually-fetch-the-latest-binary-release-from-github)
+  - [Option 4: Compile from source](#option-4-compile-from-source)
+
+## Option 1 (Mac OS only): install or upgrade from Homebrew
+
+From your Mac OS terminal, run the following command:
+
+```shell
+brew install dagger/tap/dagger
+```
+
+If dagger is already installed, you can upgrade it using this command:
+
+```shell
+brew update; brew upgrade dagger
+```
+
+> :bulb: Verify the installation with `dagger version`.
+
+## Option 2: install or upgrade from a shell script
+
+From a terminal, run the following command:
+
+```shell
+curl -sfL https://releases.dagger.io/dagger/install.sh | sh
+```
+
+You now have the dagger binary in the local directory under `./bin/dagger`.
+
+You can then install it globally on your system:
+
+```shell
+sudo mv ./bin/dagger /usr/local/bin
+```
+
+> :bulb: Verify the installation with `dagger version`.
+
+## Option 3: Manually fetch the latest binary release from Github
+
+Open your web browser to [the latest release](https://github.com/dagger/dagger/releases/latest).
+
+From the **assets** section, download the archive corresponding to your OS and Arch.
+
+> :bulb: Verify the installation with `dagger version`.
+
+## Option 4: Compile from source
+
+You will need [Go](https://golang.org) version 1.16 or later.
+
+1. Clone the dagger repository
+
+```shell
+git clone https://github.com/dagger/dagger.git
+```
+
+2. Build the `dagger` binary.
+
+```shell
+cd dagger; make
+```
+
+3. Copy the `dagger` tool to a location listed in your `$PATH`. For example, to copy it to `/usr/local/bin`:
+
+```shell
+cp ./cmd/dagger/dagger /usr/local/bin
+```
+
+> :bulb: Verify the installation with `dagger version`.
--- a/docs/operator.md
+++ b/docs/operator.md
@@ -0,0 +1,43 @@
+# Dagger Operator Manual
+
+## Custom buildkit setup
+
+Dagger can be configured to use an existing buildkit daemon, running either locally or remotely. This can be done using two environment variables: `BUILDKIT_HOST` and `DOCKER_HOST`.
+
+To use a buildkit daemon listening on TCP port `1234` on localhost:
+
+```
+$ export BUILDKIT_HOST=tcp://localhost:1234
+```
+
+To use a buildkit daemon running in a container named "super-buildkit" on the local docker host:
+
+```
+$ export BUILDKIT_HOST=docker-container://super-buildkit
+```
+
+To use a buildkit daemon running on a remote docker host (be careful to properly secure remotely accessible docker hosts!)
+
+```
+$ export BUILDKIT_HOST=docker-container://super-buildkit
+$ export DOCKER_HOST=tcp://my-remote-docker-host:2376
+```
+
+
+## OpenTracing Support
+
+Both Dagger and buildkit support opentracing. To capture traces to
+[Jaeger](https://github.com/jaegertracing/jaeger), ), set the `JAEGER_TRACE` environment variable to the collection address.
+
+A `docker-compose` file is available to help bootstrap the tracing environment:
+
+```sh
+docker-compose -f ./tracing.compose.yaml up -d
+export JAEGER_TRACE=localhost:6831
+export BUILDKIT_HOST=docker-container://dagger-buildkitd-jaeger
+
+dagger compute ...
+```
+
+You can then go to [http://localhost:16686/](http://localhost:16686/) in your browser to see the traces.
+
--- a/docs/programming.md
+++ b/docs/programming.md
@@ -0,0 +1,208 @@
+# Dagger Programming Guide
+
+## Overview
+
+1. A developer writes a *plan* specifying how to deliver their application. Plans are written in the [Cue](https://cuelang.org) data language.
+2. Dagger executes plans in isolated *environments*. Each environment has its own configuration and state.
+
+## Programming in Cue
+
+[Cue](https://cuelang.org) is a next-generation data language by Marcel van Lohuizen and the spiritual successor
+of GCL, the language used to configure all of Google's infrastructure. 
+
+Cue extends JSON with powerful features:
+
+* Composition: layering, templating, references
+* Correctness: types, schemas
+* Developer experience: comments, packages, first-class tooling, builtin functions
+* And mucn more.
+
+To get started with Cue, we recommend the following resources:
+
+* [Cuetorials](https://cuetorials.com)
+* [Cue playground](https://cuelang.org/play/)
+
+
+## Writing your first plan
+
+To create a Dagger plan:
+
+1. Create a new directory anywhere in your git repository.
+
+For example: `mkdir staging`.
+
+2. Create a new file with the *.cue* extension, and open it with any text editor or IDE.
+
+For example: `staging.cue`.
+
+3. Describe each relay in your plan as a field in the cue configuration.
+
+For example:
+
+```
+package main
+
+import (
+	"dagger.io/docker"
+	"dagger.io/git"
+)
+
+// Relay for fetching a git repository
+repo: git.#Repository & {
+	remote: "https://github.com/dagger/dagger"
+	ref: "main"
+}
+
+// Relay for building a docker image
+ctr: docker.#Build & {
+	source: repo
+}
+```
+
+For more inspiration, see these examples:
+* [Deploy a static page to S3](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-static-page-to-s3)
+* [Deploy a simple React application](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-simple-react-application)
+* [Deploy a complete JAMstack app](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-a-complete-jamstack-app)
+* [Provision a Kubernetes cluster on AWS](https://github.com/dagger/dagger/blob/main/examples/README.md#provision-a-kubernetes-cluster-on-aws)
+* [Add HTTP monitoring to your application](https://github.com/dagger/dagger/blob/main/examples/README.md#add-http-monitoring-to-your-application)
+* [Deploy an application to your Kubernetes cluster](https://github.com/dagger/dagger/blob/main/examples/README.md#deploy-an-application-to-your-kubernetes-cluster)
+
+
+4. Extend your plan with relay definitions from [Dagger Universe](../stdlib), an encyclopedia of cue packages curated by the Dagger community.
+
+5. If you can't find the relay you need in the Universe, you can simply create your own.
+
+For example:
+
+```
+import (
+	"strings"
+)
+
+// Create a relay definition which generates a greeting message
+#Greeting: {
+	salutation: string | *"hello"
+	name: string | *"world"
+	message: "\(strings.ToTitle(salutation)), \(name)!"
+}
+```
+
+You may then create any number of relays from the same definition:
+
+```
+french: #Greeting & {
+	salutation: "bonjour"
+	name: "monde"
+}
+
+american: #Greeting & {
+	salutation: "hi"
+	name: "y'all"
+}
+```
+
+
+## Concepts
+
+### Plans
+
+A *plan* specifies, in code, how to deliver a particular application in a particular way.
+
+It lays out the application's supply chain as a graph of interconnected nodes:
+
+* Development tools: source control, CI, build systems, testing systems
+* Hosting infrastructure: compute, storage, networking, databases, CDN..
+* Software dependencies: operating systems, languages, libraries, frameworks, etc.
+
+The graph models the flow of code and data through the supply chain:
+* source code flows from a git repository to a build system;
+* system dependencies are combined in a docker image, then uploaded to a registry;
+* configuration files are generated then sent to a compute cluster or load balancer;
+* etc.
+
+Dagger plans are written in [Cue](https://cuelang.org), a powerful declarative language by the creator of GQL, the language used to deploy all applications at Google.
+
+
+### Environments
+
+An *environment* is a live implementation of a *plan*, with its own user inputs and state.
+The same plan can be executed in multiple environments, for example to differentiate production from staging.
+
+An environment can be updated with `dagger up`. When updating an environment, Dagger determines which inputs have
+changed since the last update, and runs them through the corresponding pipelines to produce new outputs.
+
+For example, if an application has a new version of its frontend source code available, but no changes to
+the frontend, it will build, test and deploy the new frontend, without changing the backend.
+
+### Relays
+
+*Relays* are the basic components of a *plan*. Each relay is a node in the graph defined by the plan,
+performing the task assigned to that node. For example one relay fetches source code; another runs a build;
+another uploads a container image; etc.
+
+Relays are standalone software components: they are defined in [Cue](https://cuelang.org), but can
+execute code in any language using the [Dagger pipeline API](FIXME).
+
+A relay is made of 3 parts:
+* Inputs: data received from the user, or upstream relays
+* A processing pipeline: code executed against each new input, using the [pipeline API](FIXME)
+* Outputs: data produced by the processing pipeline
+
+Relays run in parallel, with their inputs and outputs interconnected into a special kind of graph,
+called a *DAG*. When a relay receives a new input, it runs it through the processing pipeline,
+and produces new outputs, which are propagated to downstream relays as inputs, and so on.
+
+
+### Using third-party relays
+
+Cue includes a complete package system. This makes it easy to create a complex plan in very few
+lines of codes, simply by importing relays from third-party packages.
+
+For example, to create a plan involving Github, Heroku and Amazon RDS, one might import the three
+corresponding packages:
+
+```
+import (
+	"dagger.io/github"
+	"dagger.io/heroku"
+	"dagger.io/amazon/rds"
+)
+
+repo: github.#Repository & {
+	// Github configuration values
+}
+
+backend: heroku.#App & {
+	// Heroku configuration values
+}
+
+db: rds.#Database & {
+	// RDS configuration values
+}
+```
+
+
+### Creating a new relay
+
+Sometimes there is no third-party relay available for a particular task in your workflow; or it may exist but need to be customized.
+
+A relay is typically contained in a [cue definition](https://cuetorials.com/overview/foundations/#definitions), with the definition name describing its function.
+For example a relay for a git repository might be defined as `#Repository`.
+
+The processing pipeline is a crucial feature of Dagger. It uses the [LLB](https://github.com/moby/buildkit)
+executable format pioneered by the Buildkit project. It allows Dagger components to run
+sophisticated pipelines to ingest produce artifacts such as source code, binaries, database exports, etc.
+Best of all, LLB pipelines can securely build and run any docker container, effectively making Dagger
+scriptable in any language.
+
+### Docker compatibility
+
+Thanks to its native support of LLB, Dagger offers native compatibility with Docker.
+
+This makes it very easy to extend an existing Docker-based workflow, including:
+
+* Reusing Dockerfiles and docker-compose files without modification
+* Wrapping other deployment tools in a Dagger relay by running them inside a container
+* Robust multi-arch and multi-OS support, including Arm and Windows.
+* Integration with existing Docker engines and registries
+* Integration with Docker for Mac and Docker for Windows on developer machines
--- a/docs/vs.md
+++ b/docs/vs.md
@@ -0,0 +1,41 @@
+# Dagger vs. Other Software
+
+
+## Dagger vs. PaaS (Heroku, Firebase, etc.)
+
+*Summary: Dagger can be used with or without a PaaS system.*
+
+A PaaS system is a complete platform for deploying and running certain types of applications.
+
+* The benefit of using a PaaS system is convenience: developers don't have to worry about the many details of deployment: everything just works.
+* The drawback of using a PaaS system is lack of flexibility: only certain types of applications are supported.
+
+As an application grows, it is almost certain to outgrow the capabilities of a PaaS system, leaving no choice but to look for alternatives. A good strategy is to choose the right platform for each component. Some components continue to run on a PaaS system; others run on specialized infrastructure. This strategy can be implemented with Dagger: each component gets its own deployment plan expressed as code, and Dagger glues it all together into a single workflow.
+
+
+## Dagger vs. artisanal deploy scripts
+
+*Summary: Dagger can augment your deploy scripts, and later help you simplify or even remove them.*
+
+Most applications don't fit entirely in any major PaaS system. Instead they are deployed by a patchwork of tools, usually glued together by an artisanal script.
+
+A deploy script may be written in virtually any scripting language. The most commonly used languages include Bash, Powershell, Make, Python, Ruby, Javascript... As well as a plethora of niche specialized languages.
+
+Most teams are unhappy with their deploy script. They are high maintenance, tend to break at the worst possible time, and are less convenient to use than a PaaS. But when you need control of your stack, what other choice is there?
+
+Dagger can either replace artisanal deploy scripts altogether, or augment them by incorporating them into a more standardized deployment system. This is a good strategy for teams which already have scripts and want to improve their deployment gradually, without the disruption of a "big bang" rewrite.
+
+## Dagger vs. CI (Github Actions, Gitlab, CircleCI, Jenkins, etc.)
+
+*Summary: Dagger can be used with or without a CI system.*
+
+Dagger is not a replacement for a CI system. It can be used to deploy applications directly from the terminal,
+or automatically as part of a CI script.
+
+## Dagger vs. Build Systems (Make, Maven, Bazel, Npm/Yarn, etc.)
+
+*Summary: Dagger can be used with or without a build system.*
+
+Most deployment workflows involve building: the process of producing executable artifacts from source code. Build systems are highly specific to the type of application, the programming language in use, etc.
+
+Dagger can integrate any build system into an overall deployment workflow. If a Dagger module is not already available for a particular build system, a custom module can easily be written, and perhaps even contributed to the open-source catalog for everyone else to use.