1. docker
  2. Commit cb6bcfd6bc1f71da324ca498dffda2c6c99e6090
Browse code

Improve (&restructure) Docker Index docs on the Docker docs.

Docker-DCO-1.1-Signed-off-by: O.S. Tezer <ostezer@gmail.com> (github: ostezer)

O.S.Tezer authored on 2014/04/18 05:13:59
Showing 5 changed files
docs/mkdocs.yml
History View file @ cb6bcfd
... ... 
@@ -82,6 +82,13 @@ pages:
82 82 
 # - ['user-guide/configuration.md', 'User Guide', 'Configuration']
83 83 
 # ./faq.md
84 84
85 
+# Docker Index docs:
86 
+- ['index/index.md', '**HIDDEN**']
87 
+# - ['index/home.md', 'Docker Index', 'Help']
88 
+- ['index/home.md', 'Docker Index', 'Accounts']
89 
+- ['index/home.md', 'Docker Index', 'Repositories']
90 
+- ['index/home.md', 'Docker Index', 'Trusted Builds']
91 
+
85 92 
 # Reference
86 93 
 - ['reference/index.md', '**HIDDEN**']
87 94 
 - ['reference/commandline/cli.md', 'Reference', 'Command line']
... ... 
@@ -106,11 +113,6 @@ pages:
106 106 
 - ['contributing/devenvironment.md', 'Contribute', 'Development environment']
107 107 
 # - ['about/license.md', 'About', 'License']
108 108
109 
-# Docker Index docs:
110 
-- ['index/index.md', '**HIDDEN**']
111 
-- ['index/home.md', 'Docker Index', 'Help']
112 
-- ['index/docs.md', 'Docker Index', 'Documentation']
113 
-
114 109 
 - ['jsearch.md', '**HIDDEN**']
115 110
116 111 
 # - ['static_files/README.md', 'static_files', 'README']
docs/sources/index/accounts.md
History View file @ cb6bcfd
117 112 
new file mode 100644
... ... 
@@ -0,0 +1,31 @@
0 
+page_title: Accounts in the Docker Index
1 
+page_description: Docker Index accounts
2 
+page_keywords: Docker, docker, index, accounts, plans, Dockerfile, Docker.io, docs, documentation
3 
+
4 
+# Accounts in the Docker Index
5 
+
6 
+## Docker IO and Docker Index Accounts
7 
+
8 
+You can `search` for Docker images and `pull` them from the [Docker Index]
9 
+(https://index.docker.io) without signing in or even having an account. However,
10 
+in order to `push` images, leave comments or to *star* a repository, you are going
11 
+to need a [Docker IO](https://www.docker.io) account.
12 
+
13 
+### Registration for a Docker IO Account
14 
+
15 
+You can get a Docker IO account by [signing up for one here]
16 
+(https://index.docker.io/account/signup/). A valid email address is required to
17 
+register, which you will need to verify for account activation.
18 
+
19 
+### Email activation process
20 
+
21 
+You need to have at least one verified email address to be able to use your
22 
+Docker IO account. If you can't find the validation email, you can request
23 
+another by visiting the [Resend Email Confirmation]
24 
+(https://index.docker.io/account/resend-email-confirmation/) page.
25 
+
26 
+### Password reset process
27 
+
28 
+If you can't access your account for some reason, you can reset your password
29 
+from the [*Password Reset*](https://www.docker.io/account/forgot-password/)
30 
+page.
0 31 
\ No newline at end of file
docs/sources/index/builds.md
History View file @ cb6bcfd
1 32 
new file mode 100644
... ... 
@@ -0,0 +1,118 @@
0 
+page_title: Trusted Builds in the Docker Index
1 
+page_description: Docker Index Trusted Builds
2 
+page_keywords: Docker, docker, index, accounts, plans, Dockerfile, Docker.io, docs, documentation, trusted, builds, trusted builds
3 
+
4 
+# Trusted Builds in the Docker Index
5 
+
6 
+## Trusted Builds
7 
+
8 
+*Trusted Builds* is a special feature allowing you to specify a source
9 
+repository with a *Dockerfile* to be built by the Docker build clusters. The
10 
+system will clone your repository and build the Dockerfile using the repository
11 
+as the context. The resulting image will then be uploaded to the index and
12 
+marked as a `Trusted Build`.
13 
+
14 
+Trusted Builds have a number of advantages. For example, users of *your* Trusted
15 
+Build can be certain that the resulting image was built exactly how it claims
16 
+to be.
17 
+
18 
+Furthermore, the Dockerfile will be available to anyone browsing your repository
19 
+on the Index. Another advantage of the Trusted Builds feature is the automated
20 
+builds. This makes sure that your repository is always up to date.
21 
+
22 
+### Linking with a GitHub account
23 
+
24 
+In order to setup a Trusted Build, you need to first link your Docker Index
25 
+account with a GitHub one. This will allow the Docker Index to see your
26 
+repositories.
27 
+
28 
+> *Note:* We currently request access for *read* and *write* since the Index
29 
+> needs to setup a GitHub service hook. Although nothing else is done with
30 
+> your account, this is how GitHub manages permissions, sorry!
31 
+
32 
+### Creating a Trusted Build
33 
+
34 
+You can [create a Trusted Build](https://index.docker.io/builds/github/select/)
35 
+from any of your public GitHub repositories with a Dockerfile.
36 
+
37 
+> **Note:** We currently only support public repositories. To have more than
38 
+> one Docker image from the same GitHub repository, you will need to set up one
39 
+> Trusted Build per Dockerfile, each using a different image name. This rule
40 
+> applies to building multiple branches on the same GitHub repository as well.
41 
+
42 
+### GitHub organizations
43 
+
44 
+GitHub organizations appear once your membership to that organization is
45 
+made public on GitHub. To verify, you can look at the members tab for your
46 
+organization on GitHub.
47 
+
48 
+### GitHub service hooks
49 
+
50 
+You can follow the below steps to configure the GitHub service hooks for your
51 
+Trusted Build:
52 
+
53 
+<table class="table table-bordered">
54 
+  <thead>
55 
+    <tr>
56 
+      <th>Step</th>
57 
+      <th>Screenshot</th>
58 
+      <th>Description</th>
59 
+    </tr>
60 
+  </thead>
61 
+  <tbody>
62 
+    <tr>
63 
+      <td>1.</td>
64 
+      <td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_settings.png"></td>
65 
+      <td>Login to Github.com, and visit your Repository page. Click on the repository "Settings" link. You will need admin rights to the repository in order to do this. So if you don't have admin rights, you will need to ask someone who does.</td>
66 
+    </tr>
67 
+    <tr>
68 
+      <td>2.</td>
69 
+      <td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_service_hooks.png" alt="Service Hooks"></td>
70 
+      <td>Click on the "Service Hooks" link</td></tr><tr><td>3.</td><td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_docker_service_hook.png" alt="Find the service hook labeled Docker"></td><td>Find the service hook labeled "Docker" and click on it.</td></tr><tr><td>4.</td><td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_service_hook_docker_activate.png" alt="Activate Service Hooks"></td>
71 
+      <td>Click on the "Active" checkbox and then the "Update settings" button, to save changes.</td>
72 
+    </tr>
73 
+  </tbody>
74 
+</table>
75 
+
76 
+### The Dockerfile and Trusted Builds
77 
+
78 
+During the build process, we copy the contents of your Dockerfile. We also
79 
+add it to the Docker Index for the Docker community to see on the repository
80 
+page.
81 
+
82 
+### README.md
83 
+
84 
+If you have a `README.md` file in your repository, we will use that as the
85 
+repository's full description.
86 
+
87 
+> **Warning:** If you change the full description after a build, it will be
88 
+> rewritten the next time the Trusted Build has been built. To make changes,
89 
+> modify the README.md from the Git repository. We will look for a README.md
90 
+> in the same directory as your Dockerfile.
91 
+
92 
+### Build triggers
93 
+
94 
+If you need another way to trigger your Trusted Builds outside of GitHub, you
95 
+can setup a build trigger. When you turn on the build trigger for a Trusted
96 
+Build, it will give you a URL to which you can send POST requests. This will
97 
+trigger the Trusted Build process, which is similar to GitHub webhooks.
98 
+
99 
+> **Note:** You can only trigger one build at a time and no more than one
100 
+> every five minutes. If you have a build already pending, or if you already
101 
+> recently submitted a build request, those requests *will be ignored*.
102 
+> You can find the logs of last 10 triggers on the settings page to verify
103 
+> if everything is working correctly.
104 
+
105 
+### Repository links
106 
+
107 
+Repository links are a way to associate one Trusted Build with another. If one
108 
+gets updated, linking system also triggers a build for the other Trusted Build.
109 
+This makes it easy to keep your Trusted Builds up to date.
110 
+
111 
+To add a link, go to the settings page of a Trusted Build and click on
112 
+*Repository Links*. Then enter the name of the repository that you want have
113 
+linked.
114 
+
115 
+> **Warning:** You can add more than one repository link, however, you should
116 
+> be very careful. Creating a two way relationship between Trusted Builds will
117 
+> cause a never ending build loop.
docs/sources/index/docs.md
History View file @ cb6bcfd
0 118 
deleted file mode 100644
... ... 
@@ -1,236 +0,0 @@
1 
-page_title: The Documentation
2 
-page_description: The Docker Index help documentation
3 
-page_keywords: Docker, docker, index, accounts, plans, Dockerfile, Docker.io, docs, documentation
4 
-
5 
-# The Documentation
6 
-
7 
-## Docker IO and Docker Index Accounts
8 
-
9 
-You can `search` for Docker images and `pull` them from the [Docker Index]
10 
-(https://index.docker.io) without signing in or even having an account. However,
11 
-in order to `push` images, leave comments or to *star* a repository, you are going
12 
-to need a [Docker IO](https://www.docker.io) account.
13 
-
14 
-### Registration for a Docker IO Account
15 
-
16 
-You can get a Docker IO account by [signing up for one here]
17 
-(https://index.docker.io/account/signup/). A valid email address is required to
18 
-register, which you will need to verify for account activation.
19 
-
20 
-### Email activation process
21 
-
22 
-You need to have at least one verified email address to be able to use your
23 
-Docker IO account. If you can't find the validation email, you can request
24 
-another by visiting the [Resend Email Confirmation]
25 
-(https://index.docker.io/account/resend-email-confirmation/) page.
26 
-
27 
-### Password reset process
28 
-
29 
-If you can't access your account for some reason, you can reset your password
30 
-from the [*Password Reset*](https://www.docker.io/account/forgot-password/)
31 
-page.
32 
-
33 
-## Searching for repositories and images
34 
-
35 
-You can `search` for all the publicly available repositories and images using
36 
-Docker. If a repository is not public (i.e., private), it won't be listed on
37 
-the Index search results. To see repository statuses, you can look at your
38 
-[profile page](https://index.docker.io/account/).
39 
-
40 
-## Repositories
41 
-
42 
-### Stars
43 
-
44 
-Stars are a way to show that you like a repository. They are also an easy way
45 
-of bookmark your favorites.
46 
-
47 
-### Comments
48 
-
49 
-You can interact with other members of the Docker community and maintainers by
50 
-leaving comments on repositories. If you find any comments that are not
51 
-appropriate, you can flag them for the Index admins' review.
52 
-
53 
-### Private Docker Repositories
54 
-
55 
-To work with a private repository on the Docker Index, you will need to add one
56 
-via the [Add Repository](https://index.docker.io/account/repositories/add) link.
57 
-Once the private repository is created, you can `push` and `pull` images to and
58 
-from it using Docker.
59 
-
60 
-> *Note:* You need to be signed in and have access to work with a private
61 
-> repository.
62 
-
63 
-Private repositories are just like public ones. However, it isn't possible to
64 
-browse them or search their content on the public index. They do not get cached
65 
-the same way as a public repository either.
66 
-
67 
-It is possible to give access to a private repository to those whom you
68 
-designate (i.e., collaborators) from its settings page.
69 
-
70 
-From there, you can also switch repository status (*public* to *private*, or
71 
-viceversa). You will need to have an available private repository slot open
72 
-before you can do such a switch. If you don't have any, you can always upgrade
73 
-your [Docker Index plan](https://index.docker.io/plans/).
74 
-
75 
-### Collaborators and their role
76 
-
77 
-A collaborator is someone you want to give access to a private repository. Once
78 
-designated, they can `push` and `pull`. Although, they will not be allowed to
79 
-perform any administrative tasks such as deleting the repository or changing its
80 
-status from private to public.
81 
-
82 
-> **Note:** A collaborator can not add other collaborators. Only the owner of
83 
-> the repository has administrative access.
84 
-
85 
-### Webhooks
86 
-
87 
-You can configure webhooks on the repository settings page. A webhook is called
88 
-only after a successful `push` is made. The webhook calls are HTTP POST requests
89 
-with a JSON payload similar to the example shown below.
90 
-
91 
-> **Note:** For testing, you can try an HTTP request tool like
92 
-> [requestb.in](http://requestb.in/).
93 
-
94 
-*Example webhook JSON payload:*
95 
-
96 
-    {
97 
-       "push_data":{
98 
-          "pushed_at":1385141110,
99 
-          "images":[
100 
-             "imagehash1",
101 
-             "imagehash2",
102 
-             "imagehash3"
103 
-          ],
104 
-          "pusher":"username"
105 
-       },
106 
-       "repository":{
107 
-          "status":"Active",
108 
-          "description":"my docker repo that does cool things",
109 
-          "is_trusted":false,
110 
-          "full_description":"This is my full description",
111 
-          "repo_url":"https://index.docker.io/u/username/reponame/",
112 
-          "owner":"username",
113 
-          "is_official":false,
114 
-          "is_private":false,
115 
-          "name":"reponame",
116 
-          "namespace":"username",
117 
-          "star_count":1,
118 
-          "comment_count":1,
119 
-          "date_created":1370174400,
120 
-          "dockerfile":"my full dockerfile is listed here",
121 
-          "repo_name":"username/reponame"
122 
-       }
123 
-    }
124 
-
125 
-## Trusted Builds
126 
-
127 
-*Trusted Builds* is a special feature allowing you to specify a source
128 
-repository with a *Dockerfile* to be built by the Docker build clusters. The
129 
-system will clone your repository and build the Dockerfile using the repository
130 
-as the context. The resulting image will then be uploaded to the index and
131 
-marked as a `Trusted Build`.
132 
-
133 
-Trusted Builds have a number of advantages. For example, users of *your* Trusted
134 
-Build can be certain that the resulting image was built exactly how it claims
135 
-to be.
136 
-
137 
-Furthermore, the Dockerfile will be available to anyone browsing your repository
138 
-on the Index. Another advantage of the Trusted Builds feature is the automated
139 
-builds. This makes sure that your repository is always up to date.
140 
-
141 
-### Linking with a GitHub account
142 
-
143 
-In order to setup a Trusted Build, you need to first link your Docker Index
144 
-account with a GitHub one. This will allow the Docker Index to see your
145 
-repositories.
146 
-
147 
-> *Note:* We currently request access for *read* and *write* since the Index
148 
-> needs to setup a GitHub service hook. Although nothing else is done with
149 
-> your account, this is how GitHub manages permissions, sorry!
150 
-
151 
-### Creating a Trusted Build
152 
-
153 
-You can [create a Trusted Build](https://index.docker.io/builds/github/select/)
154 
-from any of your public GitHub repositories with a Dockerfile.
155 
-
156 
-> **Note:** We currently only support public repositories. To have more than
157 
-> one Docker image from the same GitHub repository, you will need to set up one
158 
-> Trusted Build per Dockerfile, each using a different image name. This rule
159 
-> applies to building multiple branches on the same GitHub repository as well.
160 
-
161 
-### GitHub organizations
162 
-
163 
-GitHub organizations appear once your membership to that organization is
164 
-made public on GitHub. To verify, you can look at the members tab for your
165 
-organization on GitHub.
166 
-
167 
-### GitHub service hooks
168 
-
169 
-You can follow the below steps to configure the GitHub service hooks for your
170 
-Trusted Build:
171 
-
172 
-<table class="table table-bordered">
173 
-  <thead>
174 
-    <tr>
175 
-      <th>Step</th>
176 
-      <th>Screenshot</th>
177 
-      <th>Description</th>
178 
-    </tr>
179 
-  </thead>
180 
-  <tbody>
181 
-    <tr>
182 
-      <td>1.</td>
183 
-      <td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_settings.png"></td>
184 
-      <td>Login to Github.com, and visit your Repository page. Click on the repository "Settings" link. You will need admin rights to the repository in order to do this. So if you don't have admin rights, you will need to ask someone who does.</td>
185 
-    </tr>
186 
-    <tr>
187 
-      <td>2.</td>
188 
-      <td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_service_hooks.png" alt="Service Hooks"></td>
189 
-      <td>Click on the "Service Hooks" link</td></tr><tr><td>3.</td><td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_docker_service_hook.png" alt="Find the service hook labeled Docker"></td><td>Find the service hook labeled "Docker" and click on it.</td></tr><tr><td>4.</td><td><img src="https://d207aa93qlcgug.cloudfront.net/0.8/img/github_service_hook_docker_activate.png" alt="Activate Service Hooks"></td>
190 
-      <td>Click on the "Active" checkbox and then the "Update settings" button, to save changes.</td>
191 
-    </tr>
192 
-  </tbody>
193 
-</table>
194 
-
195 
-### The Dockerfile and Trusted Builds
196 
-
197 
-During the build process, we copy the contents of your Dockerfile. We also
198 
-add it to the Docker Index for the Docker community to see on the repository
199 
-page.
200 
-
201 
-### README.md
202 
-
203 
-If you have a `README.md` file in your repository, we will use that as the
204 
-repository's full description.
205 
-
206 
-> **Warning:** If you change the full description after a build, it will be
207 
-> rewritten the next time the Trusted Build has been built. To make changes,
208 
-> modify the README.md from the Git repository. We will look for a README.md
209 
-> in the same directory as your Dockerfile.
210 
-
211 
-### Build triggers
212 
-
213 
-If you need another way to trigger your Trusted Builds outside of GitHub, you
214 
-can setup a build trigger. When you turn on the build trigger for a Trusted
215 
-Build, it will give you a URL to which you can send POST requests. This will
216 
-trigger the Trusted Build process, which is similar to GitHub webhooks.
217 
-
218 
-> **Note:** You can only trigger one build at a time and no more than one
219 
-> every five minutes. If you have a build already pending, or if you already
220 
-> recently submitted a build request, those requests *will be ignored*.
221 
-> You can find the logs of last 10 triggers on the settings page to verify
222 
-> if everything is working correctly.
223 
-
224 
-### Repository links
225 
-
226 
-Repository links are a way to associate one Trusted Build with another. If one
227 
-gets updated, linking system also triggers a build for the other Trusted Build.
228 
-This makes it easy to keep your Trusted Builds up to date.
229 
-
230 
-To add a link, go to the settings page of a Trusted Build and click on
231 
-*Repository Links*. Then enter the name of the repository that you want have
232 
-linked.
233 
-
234 
-> **Warning:** You can add more than one repository link, however, you should
235 
-> be very careful. Creating a two way relationship between Trusted Builds will
236 
-> cause a never ending build loop.
237 1 
\ No newline at end of file
docs/sources/index/repos.md
History View file @ cb6bcfd
238 2 
new file mode 100644
... ... 
@@ -0,0 +1,97 @@
0 
+page_title: Repositories and Images in the Docker Index
1 
+page_description: Docker Index repositories
2 
+page_keywords: Docker, docker, index, accounts, plans, Dockerfile, Docker.io, docs, documentation
3 
+
4 
+# Repositories and Images in the Docker Index
5 
+
6 
+## Searching for repositories and images
7 
+
8 
+You can `search` for all the publicly available repositories and images using
9 
+Docker. If a repository is not public (i.e., private), it won't be listed on
10 
+the Index search results. To see repository statuses, you can look at your
11 
+[profile page](https://index.docker.io/account/).
12 
+
13 
+## Repositories
14 
+
15 
+### Stars
16 
+
17 
+Stars are a way to show that you like a repository. They are also an easy way
18 
+of bookmark your favorites.
19 
+
20 
+### Comments
21 
+
22 
+You can interact with other members of the Docker community and maintainers by
23 
+leaving comments on repositories. If you find any comments that are not
24 
+appropriate, you can flag them for the Index admins' review.
25 
+
26 
+### Private Docker Repositories
27 
+
28 
+To work with a private repository on the Docker Index, you will need to add one
29 
+via the [Add Repository](https://index.docker.io/account/repositories/add) link.
30 
+Once the private repository is created, you can `push` and `pull` images to and
31 
+from it using Docker.
32 
+
33 
+> *Note:* You need to be signed in and have access to work with a private
34 
+> repository.
35 
+
36 
+Private repositories are just like public ones. However, it isn't possible to
37 
+browse them or search their content on the public index. They do not get cached
38 
+the same way as a public repository either.
39 
+
40 
+It is possible to give access to a private repository to those whom you
41 
+designate (i.e., collaborators) from its settings page.
42 
+
43 
+From there, you can also switch repository status (*public* to *private*, or
44 
+viceversa). You will need to have an available private repository slot open
45 
+before you can do such a switch. If you don't have any, you can always upgrade
46 
+your [Docker Index plan](https://index.docker.io/plans/).
47 
+
48 
+### Collaborators and their role
49 
+
50 
+A collaborator is someone you want to give access to a private repository. Once
51 
+designated, they can `push` and `pull`. Although, they will not be allowed to
52 
+perform any administrative tasks such as deleting the repository or changing its
53 
+status from private to public.
54 
+
55 
+> **Note:** A collaborator can not add other collaborators. Only the owner of
56 
+> the repository has administrative access.
57 
+
58 
+### Webhooks
59 
+
60 
+You can configure webhooks on the repository settings page. A webhook is called
61 
+only after a successful `push` is made. The webhook calls are HTTP POST requests
62 
+with a JSON payload similar to the example shown below.
63 
+
64 
+> **Note:** For testing, you can try an HTTP request tool like
65 
+> [requestb.in](http://requestb.in/).
66 
+
67 
+*Example webhook JSON payload:*
68 
+
69 
+    {
70 
+       "push_data":{
71 
+          "pushed_at":1385141110,
72 
+          "images":[
73 
+             "imagehash1",
74 
+             "imagehash2",
75 
+             "imagehash3"
76 
+          ],
77 
+          "pusher":"username"
78 
+       },
79 
+       "repository":{
80 
+          "status":"Active",
81 
+          "description":"my docker repo that does cool things",
82 
+          "is_trusted":false,
83 
+          "full_description":"This is my full description",
84 
+          "repo_url":"https://index.docker.io/u/username/reponame/",
85 
+          "owner":"username",
86 
+          "is_official":false,
87 
+          "is_private":false,
88 
+          "name":"reponame",
89 
+          "namespace":"username",
90 
+          "star_count":1,
91 
+          "comment_count":1,
92 
+          "date_created":1370174400,
93 
+          "dockerfile":"my full dockerfile is listed here",
94 
+          "repo_name":"username/reponame"
95 
+       }
96 
+    }