{"id":13416448,"url":"https://github.com/jlhawn/dockramp","last_synced_at":"2025-04-06T06:31:59.675Z","repository":{"id":34022710,"uuid":"37780794","full_name":"jlhawn/dockramp","owner":"jlhawn","description":"A Client Driven Docker Image Builder","archived":false,"fork":false,"pushed_at":"2016-05-02T22:51:08.000Z","size":324,"stargazers_count":259,"open_issues_count":6,"forks_count":16,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-07-31T21:56:54.180Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlhawn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-20T18:27:10.000Z","updated_at":"2024-02-07T09:14:07.000Z","dependencies_parsed_at":"2022-07-14T01:50:28.938Z","dependency_job_id":null,"html_url":"https://github.com/jlhawn/dockramp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlhawn%2Fdockramp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlhawn%2Fdockramp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlhawn%2Fdockramp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlhawn%2Fdockramp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlhawn","download_url":"https://codeload.github.com/jlhawn/dockramp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445649,"owners_count":20939952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T21:00:59.000Z","updated_at":"2025-04-06T06:31:59.268Z","avatar_url":"https://github.com/jlhawn.png","language":"Go","funding_links":[],"categories":["Docker Images","Dev Tools","Go"],"sub_categories":["Builder"],"readme":"# Dockramp\n\nA Client-driven Docker Container Image Builder\n\n![truck-ramp](https://cloud.githubusercontent.com/assets/1441929/8937404/0371f5da-350d-11e5-9636-f0a8e3dae620.jpg)\n\n## Features\n\nDocker 1.8.0 will introduce a new API endpoint for copying files and\ndirectories into a container. With this addition, anyone can now implement\ntheir own build system using the Docker Remote API. **Dockramp** is the first\nproof of concept for an alternative to `docker build`.\n\n- **No context uploads**\n\n  Builds will no longer wait to begin while your client uploads a (sometimes\n  large) context directory to the Docker daemon. In **Dockramp**, files and\n  directories are only transfered when they need to be: on a `COPY` or\n  `EXTRACT` instruction. You'll notice that builds start much faster than they\n  ever would have using `docker build`.\n\n- **Efficient layering and caching**\n\n  Most build instructions are only used to specify metadata and other options\n  for how to run your container, but `docker build` creates a new filesystem\n  layer for each of these instructions - requiring you to wait while a\n  potentially expensive filesystem commit is performed and an unnecessary\n  filesystem layer is created.\n\n  **Dockramp** differentiates these instructions from others and only performs\n  filesystem commits after instructions which typically do modify the\n  filesystem: `COPY`, `EXTRACT`, and `RUN`. All other instructions may be\n  combined together and expensive commits are only performed when needed.\n\n  Cache lookups are also more efficient: build cache data is stored locally\n  rather than on the Docker daemon so that the client can decide what set\n  of changes map to a specific image ID. These lookups can be done in constant\n  time, while `docker build` cache lookups iterate over all image layers and\n  get noticeably slower the more images you have installed.\n\n- **More expressive and extensible Dockerfile syntax**\n\n  The existing Dockerfile syntax has served many developers well for over 2\n  years, but is also limitting to those who wish to have more options for\n  some build instructions.\n\n  **Dockramp** rethinks some of the design decisions of Docker's Dockerfile\n  syntax and offers a more familiar way of scripting a build for anyone who has\n  ever written a shell script: no more cascading line continuations or\n  alternative JSON syntax, just simple space separated or quoted arguments and\n  even [heredoc](https://en.wikipedia.org/wiki/Here_document) support for more\n  complex `RUN` instructions.\n\n  See the **Dockerfile Syntax** section below for examples and notable\n  differences from Docker's Dockerfile syntax.\n\n## Installation\n\nVisit the [release page](https://github.com/jlhawn/dockramp/releases) to get\na binary for the latest version on your OS/Arch. If you'd rather compile it\nyourself (like I would), you just need `git` and `go`:\n\n```bash\nproject_dir=\"$HOME/dockramp/src/github.com/jlhawn/dockramp\"\nmkdir -p $project_dir\ngit clone https://github.com/jlhawn/dockramp.git $project_dir\nGOPATH=\"$project_dir/Godeps/_workspace:$HOME/dockramp\" go build -o /usr/local/bin/dockramp github.com/jlhawn/dockramp/cmd/dockramp\n```\n\n## Usage\n\nInvoking `dockramp` with no other arguments will use the current directory as\nthe build context and use the file named \"Dockerfile\" in the current directory\nfor build intstructions.\n\n```bash\n$ # Executes the Dockerfile in this repository.\n$ dockramp \nStep 0: FROM golang:1.4.2\nStep 1: MAINTAINER \"Josh Hawn \u003cjlhawn@docker.com\u003e (github:jlhawn)\"\nStep 2: ENV PROJ_DIR /go/src/github.com/jlhawn/dockramp\nStep 3: RUN sh -c \"mkdir -p $PROJ_DIR\"\n ---\u003e 0744c1be2f5fb40c355bace595171c180f2a7b2d19ec15e0c92da2fa0c1d7198\nStep 4: COPY . /go/src/github.com/jlhawn/dockramp\n ---\u003e 8a40aa285e0ecc70ba5361085ef2faf0e755a8dbf7f2224b377c5c0035dc22a5\nStep 5: RUN sh\nInput:\n\texport GOPATH=\"$PROJ_DIR/Godeps/_workspace:$GOPATH\"\n\tgo build -o /usr/local/bin/dockramp github.com/jlhawn/dockramp/cmd/dockramp\n\n ---\u003e 029e66e2587118f5f6c5176da65ffbde3b501b25136a637c3d700ee369104374\nSuccessfully built 029e66e2587118f5f6c5176da65ffbde3b501b25136a637c3d700ee369104374\n```\n\nYou can use the `-C` flag to specify a directory to use as the build context.\nYou can also specify any Dockerfile with the `-f` flag (this file *does not*\nneed to be within the context directory!).\n\n`dockramp` also supports many of the standard options used by `docker` and uses\nmany of the same environment variables and configuration files used by `docker`\nas well. Here is the full list of currently supported arguments:\n\n```bash\n$ dockramp --help\nUsage of dockramp:\n  --cacert=\"\": Trust certs signed only by this CA\n  --cert=\"\": TLS client certificate\n  --key=\"\": TLS client key\n  --tls=false: Use TLS client cert/key (implied by --tlsverify)\n  --tlsverify=true: Use TLS and verify the remote server certificate\n  -C=\".\": Build context directory\n  -H=\"\": Docker daemon socket/host to connect to\n  -d=false: enable debug output\n  -f=\"\": Path to Dockerfile\n  -t=\"\": Repository name (and optionally a tag) for the image\n```\n\n## Dockerfile Syntax\n\nWhile the original Dockerfile parser used by `docker build` simply scans for\ncomplete (unescaped) lines and parses each instruction arbitrarily based on the\ncommand, the Dockerfile parser in Dockramp is a more traditional parser which\nprocesses tokens from the input Dockerfile into instructions of positional\narguments.\n\nThe Dockerfile syntax used by Dockramp aims to be simple and familiar: a subset\nof unix shell syntax. Each instruction has a name, optional flag arguments, and\npositional arguments.\n\n### Tokens\n\n- **Whitespace**\n\n  Unquoted whitespace is ignored, but is used to delimit arguments to\n  instructions. Whitespace includes: literal space (` `), form feed (`\\f`),\n  carriage return (`\\r`), horizontal tab (`\\t`), vertical tab (`\\v`), or a\n  newline (`\\n`) character escaped using a backslash (`\\`).\n\n- **Comments**\n\n  Comments are specified using a hash or pound (`#`) character and cause the\n  remainder of that line to be ignored.\n\n- **Newlines**\n\n  A newline character (`\\n`) is used to end an instruction. Empty lines and\n  lines containing only whitespace are ignored.\n\n- **Arguments**\n\n  Instructions are whitespace delimited and arguments can can be single or\n  double quoted strings allowing for arguments which contain whitespace.\n\n  - **Single Quoted String**\n\n    A single quoted string is evaluated to be the literal value of the sequence\n    of characters between two single quotes (`'`). Any character (including a\n    newline) that is not a single quote may be included in the string. No\n    escape processing is done on single quoted strings.\n\n  - **Double Quoted String**\n\n    A double quoted string is evaluated to be the value of the sequence of\n    characters between two double quotes (`\"`) with some escape sequence\n    processing. Any character (including a newline) that is not a double quote\n    (unless it is escaped first as in `\\\"`) may appear between the double\n    quotes. An escaped double quote character is replaced with a double quote.\n    An escaped backslash is replaced with a single backslash. An escaped\n    newline is replaced with nothing. No other escape processing is done.\n\n  - **Raw Argument**\n\n    A raw argument is a sequence of one or more characters that are not already\n    specified above meaning no hash (`#`), single (`'`) or double (`\"`) quote\n    character, `\u003c` (used by heredocs), and any whitespace character. However,\n    any of these characters may be escaped by a backslash `\\` character.\n    Escaped sequences are replaced with the escaped character, except for\n    escaped newlines which are replaced with nothing.\n\n  Quoted tokens that are not separated by whitespace are joined into a single\n  argument value. For example, `hel\"lo wo\"'rld!'` is evaluated into a single\n  argument `hello world!`.\n\n- **Heredocs**\n\n  Some instructions, such as `RUN`, can accept an input stream in the form of\n  a [heredoc](https://en.wikipedia.org/wiki/Here_document). A heredoc is\n  specified as the last argument to an instruction in the form `\u003c\u003c` and\n  followed immediately by an alphanumeric delimiting term such as `\u003c\u003c EOF` or\n  `\u003c\u003c END`. This opens the heredoc.\n\n  The following lines will contain the literal text to be used as input to the\n  instruction. If the heredoc was opened using `\u003c\u003c-` rather than `\u003c\u003c` then\n  leading tab characters of each line will be ignored, allowing for indentation\n  of a heredoc without changing its value.\n\n  A heredoc is closed by the delimiting term appearing alone on its own line\n  (no leading or trailing whitespace).\n\n### Instructions\n\nAll instruction names are case insensitive, i.e, `RUN` and `run` are considered\nequivalent. However, all-caps is still the preferred form.\n\n- **`ADD`**\n\n  Not supported. For extracting a tar archive to a directory in the container\n  use the `EXTRACT` instruction instead. Downloading a resource from a URL into\n  the container is planned to be supported soon via some other instruction.\n\n- **`CMD`**\n\n  Provide default arguments to a container's Entrypoint.\n\n  ```\n  CMD arg ...\n  ```\n\n  - Accepts zero or more arguments.\n\n- **`COPY`**\n\n  Copy a file or directory from the build context to a location in the\n  container.\n\n  ```\n  COPY source destination\n  ```\n\n  - Requires exactly 2 arguments.\n  - `source` is relative to the build context directory.\n  - `destination` is an absolute path in the container.\n\n- **`ENTRYPOINT`**\n\n  Specify the file to execute and any permanent arguments when running the\n  container.\n\n  ```\n  ENTRYPOINT arg ...\n  ```\n\n  - Accepts zero or more arguments.\n\n- **`ENV`**\n\n  Set an environment variable for when the container runs.\n\n  ```\n  ENV key value\n  ```\n\n  - Requires exactly 2 arguments.\n\n- **`EXPOSE`**\n\n  Expose a tcp or udp port in the container to the network.\n\n  ```\n  EXPOSE portspec\n  ```\n\n  - Requires exactly 1 argument.\n\n- **`EXTRACT`**\n\n  Extract a tar archive to a directory inside the container.\n\n  ```\n  EXTRACT source destination\n  ```\n\n  - Requires exactly 2 arguments.\n  - `source` is relative to the build context directory.\n  - `destination` is an absolute path in the container and must be an existing\n    directory.\n\n- **`FROM`**\n\n  Use the specified image as the base container image to build from.\n\n  ```\n  FROM imagespec\n  ```\n\n  - Requires exactly 1 argument.\n  - `scratch` is used to indicate that the build should start with an empty\n    container filesystem.\n\n- **`LABEL`**\n\n  Add metadata to the container image.\n\n  ```\n  LABEL key value\n  ```\n\n  - Requires exactly 2 arguments.\n\n- **`MAINTAINER`**\n\n  Specify the author of the resulting container image.\n\n  ```\n  MAINTAINER name_and_info\n  ```\n\n  - Requires exactly 1 argument.\n\n- **`ONBUILD`**\n\n  Not supported.\n\n- **`RUN`**\n\n  Execute a command inside of a container.\n\n  ```\n  RUN arg ...\n  ```\n\n  - Requires at least 1 argument.\n  - Can use a heredoc to specify `stdin` to the command.\n\n- **`USER`**\n\n  Set the username or UID to use when running the container.\n\n  ```\n  USER userspec\n  ```\n\n  - Requires exactly 1 argument.\n\n- **`VOLUME`**\n\n  Create a mount point inside the container.\n\n  ```\n  VOLUME path\n  ```\n\n  - Requires exactly 1 argument.\n\n- **`WORKDIR`**\n\n  Set the working directory for the container.\n\n  ```\n  WORKDIR directory\n  ```\n\n  - Requires exactly 1 argument.\n  - `directory` is an absolute path inside the container.\n\n\n## TODO\n\n- Handle `.dockerignore`.\n- Resolve tag references to digest references using Notary before image pulls.\n- Implement various options (via flags) to many Dockerfile instructions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlhawn%2Fdockramp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlhawn%2Fdockramp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlhawn%2Fdockramp/lists"}