docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-10-31 10:34:26 +03:00
Code Activity

Merge pull request #1058 from usha-mandya/app-templates-1006

Browse Source 
1006 - Adding Docker Template content
This commit is contained in:
Usha Mandya
2019-05-14 13:18:11 +01:00
committed by GitHub
parent 864dcc1098 41759784ed
commit 1eecbfc6e4
4 changed files with 809 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
_data/toc.yaml
View File

@@ -3142,6 +3142,12 @@ manuals:
section:
- path: /app/working-with-app/
title: Working with Docker App
- sectiontitle: Docker Template
section:
- path: /app-template/working-with-template/
title: Working with Docker Template
- path: /app-template/cli-reference/
title: CLI reference
- sectiontitle: Docker Compose
section:
- path: /compose/overview/

161
app-template/api-reference.md Normal file
View File

@@ -0,0 +1,161 @@
---
title: Docker Template API reference
description: Docker Template API reference
keywords: application, template, API, definition
---
This page contains information about the Docker Template API reference.
## Service template definition
The following section provides information about the valid parameters that you can use when you create a service template definition.
```
apiVersion: v1alpha1
kind: ServiceTemplate
metadata:
name: angular
platforms:
- linux
spec:
title: Angular
description: Angular service
icon: https://cdn.worldvectorlogo.com/logos/angular-icon-1.svg
source:
image: docker.io/myorg/myservice:version
parameters:
- name: node
description: Node version
type: enum
defaultValue: "9"
values:
- value: "10"
description: "10"
- value: "9"
description: "9"
- value: "8"
description: "8"
- name: externalPort
description: External port
defaultValue: "8080"
type: hostPort
```
### root
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| apiVersion |yes | The api format version. Current latest is v1alpha1|
|kind| yes|The kind of object. Must be `ServiceTemplate` For services templates.|
### metadata
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
|name |yes | The identifier for this service. Must be unique within a given library. |
|platform| yes|A list of allowed target platforms. Possible options are `windows` and `linux`|
### spec
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| title |yes |The label for this service, as displayed when listed in `docker template` commands or in the `application-designer`|
|description| no|A short description for this service|
|icon|no|An icon representing the service. Only used in the Application Designer|
### spec/source
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| image |yes| The name of the image associated with this service template. Must be in full `repo/org/service:version` format|
### spec/parameters
The parameters section allows to specify the input parameters that are going to be used by the service.
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
|name |yes| The identifier for this parameter. Must be unique within the service parameters. |
|description| no|A short description of the parameter. Will be used as label in the Application Designer|
|type| yes|The type of the parameter. Possible options are:<ul><li>`string` - The default type, with no validation or specific features.</li><li>`enum` - Allow the user to choose a value included in a specific list of options. Must specify the values parameter.</li><li>`hostPort` - Specify that this parameter is a port that is going to be exposed. Use port format regexp validation, and avoid duplicate ports within an application.</li></ul>|
|defaultValue| yes|The default value for this parameter. For enum type, must be a valid value from the values list.|
|values| no|For enum type, specify a list of value with a value/description tuple.|
## Application template definition
The following section provides information about the valid parameters that you can use when you create a application template definition.
```
apiVersion: v1alpha1
kind: ApplicationTemplate
metadata:
name: nginx-flask-mysql
platforms:
- linux
spec:
title: Flask / NGINX / MySQL application
description: Sample Python/Flask application with an Nginx proxy and a MySQL database
services:
- name: back
serviceId: flask
parameters:
externalPort: "80"
- name: db
serviceId: mysql
- name: proxy
serviceId: nginx
```
### root
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| apiVersion |yes | The api format version. Current latest is v1alpha1|
|kind| yes|The kind of object. Must be `ApplicationTemplate` For application templates.|
### metadata
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
|name |yes | The identifier for this application template. Must be unique within a given library.|
|platform| yes|A list of allowed target platforms. Possible options are `windows` and `linux`|
### spec
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| title |yes |The label for this application template, as displayed when listed in `docker template` commands or in `application-designer` |
|description| no|A short description for this service|
### spec/services
This section lists the service templates used in the application.
| Parameter |Required? | Description |
| :----------------------|:----------------------|:----------------------------------------|
| name |yes|The name of the service. It will be used for image name and for subfolder within the application structure. |
|serviceId |yes|The id of the service to use (equivalent to the metadata/name field of the service) |
| parameters |no|A map (string to string) that can be used to override the default values of the service parameters.|
## Service configuration file
The file is mounted at `/run/configuration` in every service template container and contains the template context in a JSON format.
| Parameter |Description |
| :----------------------|:----------------------|
|ServiceId |The service id|
| name |The name of the service as specified by the application template or overridden by the user|
|parameters |A map (string to string) containing the service’s parameter values.|
| targetPath |The destination folder for the application on the host machine.|
|namespace |The service image’s namespace (org and user)|
|services |A list containing all the services of the application (see below)|
### Attributes
The items in the services list contains the following attributes:
| Parameter |Description |
| :----------------------|:----------------------|
|serviceId |The service id|
| name |The name of the service as specified by the application template or overridden by the user|
| parameters |A map (string to string) containing the service’s parameter values.|

197
app-template/cli-reference.md Normal file
View File

@@ -0,0 +1,197 @@
---
title: Docker Template CLI reference
description: Docker Template CLI reference
keywords: Docker, application template, CLI, Application Designer,
---
This page provides information about the `docker template` command.
## Overview
Docker Template is a CLI plugin that introduces a top-level `docker template`command that allows users to create new Docker applications using a library of templates. With `docker template`, you can scaffold a full project structure for a chosen technical stack or a set of technical stacks using the best practices pre-configured in a generated Dockerfile and docker-compose file.
For more information about Docker Template, see [Working with Docker Template](/ee/docker-template/working-with-template).
## `docker template` commands
To view the commands and sub-commands available in `docker template`, run:
`docker template --help`
```
Usage: docker template COMMAND
Use templates to quickly create new services
Commands:
inspect Inspect service templates or application templates
list List available templates with their information
scaffold Choose an application template or service template(s) and scaffold a new project
version Print version information
Run 'docker template COMMAND --help' for more information on a command.
```
### inspect
The `docker template inspect` command allows you to view the details of the template such as service parameters, default values, and for application templates, the list of services included in the application.
```
Usage: docker template inspect <service or application>
Inspect service templates or application templates
Options:
--format string Configure the output format (pretty|json|yaml)
(default "pretty")
```
For example:
```
docker template inspect react-java-mysql
NAME: react-java-mysql
TITLE: React / Spring / MySQL application
DESCRIPTION: Sample React application with a Spring backend and a MySQL database
SERVICES:
* PARAMETERS FOR SERVICE: front (react)
NAME DESCRIPTION TYPE DEFAULT VALUE VALUES
node Node version enum 9 10, 9, 8
externalPort External port hostPort 8080
* PARAMETERS FOR SERVICE: back (spring)
NAME DESCRIPTION TYPE DEFAULT VALUE VALUES
java Java version enum 9 10, 9, 8
groupId Group Id string com.company
artifactId Artifact Id string project
appName Application name string New App
appDescription Application description string My new SpringBoot app
externalPort External port hostPort 8080
* PARAMETERS FOR SERVICE: db (mysql)
NAME DESCRIPTION TYPE DEFAULT VALUE VALUES
version Version enum 5.7 5.7
```
### list
The `docker template list` command lists the available service and application templates.
```
Usage: docker template list
List available templates with their information
Aliases:
list, ls
Options:
--format string Configure the output format (pretty|json|yaml)
(default "pretty")
--type string Filter by type (application|service|all) (default
"all")
```
For example:
`docker template list`
```
NAME TYPE DESCRIPTION
aspnet-mssql application Sample asp.net core application with mssql database
nginx-flask-mysql application Sample Python/Flask application with an Nginx proxy and a MySQL database
nginx-golang-mysql application Sample Golang application with an Nginx proxy and a MySQL database
nginx-golang-postgres application Sample Golang application with an Nginx proxy and a PostgreSQL database
react-java-mysql application Sample React application with an Spring backend and a MySQL database
react-express-mysql application Sample React application with a NodeJS backend and a MySQL database
sparkjava-mysql application Java application and a MySQL database
spring-postgres application Sample Java application with Spring framework and a Postgres database
angular service Angular service
aspnetcore service A lean and composable framework for building web and cloud applications
consul service A highly available and distributed service discovery and KV store
django service A high-level Python Web framework
express service NodeJS web application with Express server
flask service A microframework for Python based on Werkzeug, Jinja 2 and good intentions
golang service A powerful URL router and dispatcher for golang
gwt service GWT (Google Web Toolkit) / Java service
jsf service JavaServer Faces technology establishes the standard for building server-side user interfaces.
mssql service Microsoft SQL Server for Docker Engine
mysql service Official MySQL image
nginx service An HTTP and reverse proxy server
postgres service Official PostgreSQL image
rails service A web-application framework that includes everything needed to create database-backed web applications
react service React/Redux service with Webpack hot reload
sparkjava service A micro framework for creating web applications in Java 8 with minimal effort
spring service Customizable Java/Spring template
vuejs service VueJS service
```
### scaffold
The `docker template scaffold` command allows you to generate a project structure for a template.
```
Usage: docker template scaffold application [<alias=service>...] OR scaffold [alias=]service [<[alias=]service>...]
Choose an application template or service template(s) and scaffold a new project
Examples:
docker template scaffold react-java-mysql -s back.java=10 -s front.externalPort=80
docker template scaffold react-java-mysql java=back reactjs=front -s reactjs.externalPort=80
docker template scaffold back=spring front=react -s back.externalPort=9000
docker template scaffold react-java-mysql --server=myregistry:5000 --org=myorg
Options:
--build Run docker-compose build after deploy
--name string Application name
--org string Deploy to a specific organization / docker hub
user (if not specified, it will use your
current hub login)
--path string Deploy to a specific path
--platform string Target platform (linux|windows) (default "linux")
--server string Deploy to a specific registry server (host[:port])
-s, --set stringArray Override parameters values (service.name=value)
```
For example:
`docker template scaffold react-java-mysql`
If you want to change some of the parameter values (exposed port, specific version, etc.) you can pass additional parameters, and reference the service name it applies to with `--set` or `-s`.
For example:
`docker template scaffold react-java-mysql -s back.java=10 -s front.externalPort=80`
By default, the `docker template scaffold` command generates the project structure in the current folder. However, you can specify another folder using the `--path` parameter.
For example:
`docker template scaffold react-java-mysql --path /xxx`
You can also change service names by providing aliases when scaffolding either an application template or a list of service templates.
For example:
`docker template scaffold react-java-mysql java=back reactjs=front -s reactjs.externalPort=80`
### version
The `docker template version` command displays the Docker Template version number.
```
Usage: docker template version
Print version information
```
For example:
`docker template version`
```
Version: d6c11e577c592aad69d34db6d4dc740d65291e36
Git Commit: 96ea0063b0c9aaa0cc5b5ff811b51a6e2e752be9
```

445
app-template/working-with-template.md Normal file
View File

@@ -0,0 +1,445 @@
---
title: Working with Docker Template
description: Working with Docker Application Template
keywords: Docker, application template, Application Designer,
---
## Overview
Docker Template is a CLI plugin that introduces a top-level `docker template` command that allows users to create new Docker applications by using a library of templates. There are two types of templates — service templates and application templates.
A _service template_ is a container image that generates code and contains the metadata associated with the image.
- The container image takes `/run/configuration` mounted file as input to generate assets such as code, Dockerfile, and `docker-compose.yaml` for a given service, and writes the output to the `/project` mounted folder.
- The metadata file that describes the service template is called the service definition. It contains the name of the service, description, and available parameters such as ports, volumes, etc. For a complete list of parameters that are allowed, see [Docker Template API reference](/ee/app-template/api-reference).
An _application template_ is a collection of one or more service templates.
## Create a custom service template
A Docker template contains a predefined set of service and application templates. To create a custom template based on your requirements, you must complete the following steps:
1. Create a service container image
2. Create the service template definition
3. Add the service template to the library
4. Share the service template
### Create a service container image
A service template provides the description required by Docker Template to scaffold a project. A service template runs inside a container with two bind mounts:
1. `/run/configuration`, a JSON file which contains all settings such as parameters, image name, etc. For example:
```
{
"parameters": {
"externalPort": "80",
"artifactId": "com.company.app"
},
...
}
```
2. `/project`, the output folder to which the container image writes the generated assets.
#### Basic service template
To create a basic service template, you need to create two files — a dockerfile and a docker compose file in a new folder. For example, to create a new MySQL service template, create the following files in a folder called `my-service`:
`docker-compose.yaml`
```
version: "3.6"
services:
mysql:
image: mysql
```
`Dockerfile`
```
FROM alpine
COPY docker-compose.yaml .
CMD cp docker-compose.yaml /project/
```
This adds a MySQL service to your application.
#### Create a service with code
Services that generate a template using code must contain the following files that are valid:
- A *Dockerfile* located at the root of the `my-service` folder. This is the Dockerfile that is used for the service when running the application.
- A *docker-compose.yaml* file located at the root of the `my-service` folder. The `docker-compose.yaml` file must contain the service declaration and any optional volumes or secrets.
Here’s an example of a simple NodeJS service:
```
my-service
├── Dockerfile # The Dockerfile of the service template
└── assets
├── Dockerfile # The Dockerfile of the generated service
└── docker-compose.yaml # The service declaration
```
The NodeJS service contains the following files:
`my-service/Dockerfile`
```
FROM alpine
COPY assets /assets
CMD ["cp", "/assets", "/project"]
FROM dockertemplate/interpolator:v0.0.8 as interpolator
COPY assets /assets
```
`my-service/assets/docker-compose.yaml`
```
version: "3.6"
services:
{{ .Name }}:
build: {{ .Name }}
ports:
- {{ .Parameters.externalPort }}:3000
```
`my-service/assets/Dockerfile`
```
FROM NODE:9
WORKDIR /app
COPY package.json .
RUN yarn install
COPY . .
CMD ["yarn", "run", "start"]
```
> **Note:** After scaffolding the template, you can add the default files your template contains to the `assets` folder.
The next step is to build and push the service template image to a remote repository by running the following command:
```
cd [...]/my-service
docker build -t org/my-service .
docker push org/my-service
```
To build and push the image to an instance of Docker Trusted Registry(DTR), or to an external registry, specify the name of the repository:
```
cd [...]/my-service
docker build -t myrepo:5000/my-service .
docker push myrepo:5000/my-service
```
### Create the service template definition
The service definition contains metadata that describes a service template. It contains the name of the service, description, and available parameters such as ports, volumes, etc.
After creating the service definition, you can proceed to [Add templates to Docker Template](#add-templates-to-docker-template) to add the service definition to the Docker Template repository.
Of all the available service and application definitions, Docker Template has access to only one catalog, referred to as the ‘repository’. It uses the catalog content to display service and application templates to the end user.
Here is an example of the Express service definition:
```
- apiVersion: v1alpha1 # constant
kind: ServiceTemplate # constant
metadata:
name: Express # the name of the service
spec:
title: Express # The title/label of the service
icon: https://docker-application-template.s3.amazonaws.com/assets/express.png # url for an icon
description: NodeJS web application with Express server
source:
image: org/my-service:latest
```
The most important section here is `image: org/my-service:latest`. This is the image associated with this service template. You can use this line to point to any image. For example, you can use an Express image directly from the hub `docker.io/dockertemplate/express:latest` or from the DTR private repository `myrepo:5000/my-service:latest`. The other properties in the service definition are mostly metadata for display and indexation purposes.
#### Adding parameters to the service
Now that you have created a simple express service, you can customize it based on your requirements. For example, you can choose the version of NodeJS to use when running the service.
To customize a service, you need to complete the following tasks:
1. Declare the parameters in the service definition. This tells Docker Template whether or not the CLI can accept the parameters, and allows the [Application Designer](/ee/desktop/app-designer) to be aware of the new options.
2. Use the parameters during service construction.
#### Declare the parameters
Add the parameters available to the application. The following example adds the NodeJS version and the external port:
```
- [...]
spec:
[...]
parameters:
- name: node
defaultValue: "9"
description: Node version
type: enum
values:
- value: "10"
description: "10"
- value: "9"
description: "9"
- value: "8"
description: "8"
- defaultValue: "3000"
description: External port
name: externalPort
type: hostPort
[...]
```
#### Use the parameters during service construction
When you run the service template container, a volume is mounted making the service parameters available at `/run/configuration`.
The file matches the following go struct:
```
type TemplateContext struct {
ServiceID string `json:"serviceId,omitempty"`
Name string `json:"name,omitempty"`
Parameters map[string]string `json:"parameters,omitempty"`
TargetPath string `json:"targetPath,omitempty"`
Namespace string `json:"namespace,omitempty"`
Services []ConfiguredService `json:"services,omitempty"`
}
```
Where `ConfiguredService` is:
```
type ConfiguredService struct {
ID string `json:"serviceId,omitempty"`
Name string `json:"name,omitempty"`
Parameters map[string]string `json:"parameters,omitempty"`
}
```
You can then use the file to obtain values for the parameters and use this information based on your requirements. However, in most cases, the JSON file is used to interpolate the variables. Therefore, we provide a utility called `interpolator` that expands variables in templates. For more information, see [Interpolator](#interpolator).
To use the `interpolator` image, update `my-service/Dockerfile` to use the following Dockerfile:
```
FROM dockertemplate/interpolator:v0.0.3-beta1
COPY assets .
```
> **Note:** The interpolator tag must match the version used in Docker Template. Verify this using the `docker template version` command .
This places the interpolator image in the `/assets` folder and copies the folder to the target `/project` folder. If you prefer to do this manually, use a Dockerfile instead:
```
WORKDIR /assets
CMD ["/interpolator", "-config", "/run/configuration", "-source", "/assets", "-destination", "/project"]
```
When this is complete, use the newly added node option in `my-service/assets/Dockerfile`, by replacing the line:
`FROM node:9`
with
`FROM node:{{ .Parameters.node }}`
Now, build and push the image to your repository.
### Add service template to the library
You must add the service to a repository file in order to see it when you run the `docker template ls` command, or to make the service available in the Application Designer.
#### Create the repository file
Create a local repository file called `library.yaml` anywhere on your local drive and add the newly created service definitions and application definitions to it.
`library.yaml`
```
apiVersion: v1alpha1
generated: "2018-06-13T09:24:07.392654524Z"
kind: RepositoryContent
services: # List of service templates available
- apiVersion: v1alpha1 # here is the service definition for our service template.
kind: ServiceTemplate
name: express
spec:
title: Express
[...]
```
#### Add the local repository to docker-template settings
> **Note:** You can also use the instructions in this section to add templates to the [Application Designer](/ee/desktop/app-designer).
Now that you have created a local repository and added service definitions to it, you must make Docker Template aware of these. To do this:
1. Edit `~/.docker/dockertemplate/preferences.yaml` as follows:
```
apiVersion: v1alpha1
channel: master
kind: Preferences
repositories:
- name: library-master
url: https://docker-application-template.s3.amazonaws.com/master/library.yaml
```
2. Add your local repository:
```
apiVersion: v1alpha1
channel: master
kind: Preferences
repositories:
- name: custom-services # here
url: file://path/to/my/library.yaml
- name: library-master
url: https://docker-application-template.s3.amazonaws.com/master/library.yaml
```
After updating the `preferences.yaml` file, run `docker template ls` or restart the Application Designer and select **Custom application**. The new service should now be visible in the list of available services.
### Share custom service templates
To share a custom service template, you must complete the following steps:
1. Push the image to an available endpoint (for example, Docker Hub)
2. Share the service definition (for example, GitHub)
3. Ensure the receiver has modified their `preferences.yaml` file to point to the service definition that you have shared, and are permitted to accept remote images.
## Create a custom application template
An application template is a collection of one or more service templates. You must complete the following steps to create a custom application template:
1. Create an application template definition
2. Add the application template to the library
3. Share your custom application template
### Create the application definition
An application template definition contains metadata that describes an application template. It contains information such as the name and description of the template, the services it contains, and the parameters for each of the services.
Before you create an application template definition, you must create a repository that contains the services you are planning to include in the template. For more information, see [Create the repository file](#create-the-repository-file).
For example, to create an Express and MySQL application, the application definition must be similar to the following yaml file:
```
apiVersion: v1alpha1 #constant
kind: ApplicationTemplate #constant
metadata:
name: express-mysql #the name of the application
spec:
description: Sample application with a NodeJS backend and a MySQL database
services: # list of the services
- name: back
serviceId: express # service name
parameters: # (optional) define the default application parameters
externalPort: 9000
- name: db
serviceId: mysql
title: Express / MySQL application
```
### Add the template to the library
Create a local repository file called `library.yaml` anywhere on your local drive. If you have already created the `library.yaml` file, add the application definitions to it.
`library.yaml`
```
apiVersion: v1alpha1
generated: "2018-06-13T09:24:07.392654524Z"
kind: RepositoryContent
services: # List of service templates available
- apiVersion: v1alpha1 # here is the service definition for our service template.
kind: ServiceTemplate
name: express
spec:
title: Express
[...]
templates: # List of application templates available
- apiVersion: v1alpha1 #constant
kind: ApplicationTemplate # here is the application definition for our application template
metadata:
name: express-mysql
spec:
```
### Add the local repository to `docker-template` settings
Now that you have created a local repository and added application definitions, you must make Docker Template aware of these. To do this:
1. Edit `~/.docker/dockertemplate/preferences.yaml` as follows:
```
apiVersion: v1alpha1
channel: master
kind: Preferences
repositories:
- name: library-master
url: https://docker-application-template.s3.amazonaws.com/master/library.yaml
```
2. Add your local repository:
```
apiVersion: v1alpha1
channel: master
kind: Preferences
repositories:
- name: custom-services # here
url: file://path/to/my/library.yaml
- name: library-master
url: https://docker-application-template.s3.amazonaws.com/master/library.yaml
```
After updating the `preferences.yaml` file, run `docker template ls` or restart the Application Designer and select **Custom application**. The new template should now be visible in the list of available templates.
### Share the custom application template
To share a custom application template, you must complete the following steps:
1. Push the image to an available endpoint (for example, Docker Hub)
2. Share the application definition (for example, GitHub)
3. Ensure the receiver has modified their `preferences.yaml` file to point to the application definition that you have shared, and are permitted to accept remote images.
## Interpolator
The `interpolator` utility is basically an image containing a binary which:
- takes a folder (assets folder) and the service parameter file as input,
- replaces variables in the input folder using the parameters specified by the user (for example, the service name, external port, etc), and
- writes the interpolated files to the destination folder.
The interpolator implementation uses [Golang template](https://golang.org/pkg/text/template/) to aggregate the services to create the final application. If your service template uses the `interpolator` image by default, it expects all the asset files to be located in the `/assets` folder:
`/interpolator -source /assets -destination /project`
However, you can create your own scaffolding script that performs calls to the `interpolator`.
> **Note:** It is not mandatory to use the `interpolator` utility. You can use a utility of your choice to handle parameter replacement and file copying to achieve the same result.
The following table lists the `interpolator` binary options:
| Parameter | Default value | Description |
| :----------------------|:---------------------------|:----------------------------------------|
| `-source` | none | Source file or folder to interpolate from|
| `-destination` | none | Destination file or folder to copy the interpolated files to|
| `-config` | `/run/configuration` | The path to the json configuration file |
| `-skip-template` | false | If set to `true`, it copies assets without any transformation |