1# OCI Image Format Specification
2
3
4
5[](https://pkg.go.dev/github.com/opencontainers/image-spec)
6
7The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format).
8
9**[The specification can be found here](spec.md).**
10
11This repository also provides [Go types](specs-go), [intra-blob validation tooling, and JSON Schema](schema).
12The Go types and validation should be compatible with the current Go release; earlier Go releases are not supported.
13
14Additional documentation about how this group operates:
15
16- [Code of Conduct][code-of-conduct]
17- [Roadmap](#roadmap)
18- [Releases](RELEASES.md)
19- [Project Documentation](project.md)
20
21## Running an OCI Image
22
23The OCI Image Format partner project is the [OCI Runtime Spec project](https://github.com/opencontainers/runtime-spec).
24The Runtime Specification outlines how to run a "[filesystem bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md)" that is unpacked on disk.
25At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
26At this point the OCI Runtime Bundle would be run by an OCI Runtime.
27
28This entire workflow supports the UX that users have come to expect from container engines like Docker and rkt: primarily, the ability to run an image with no additional arguments:
29
30- docker run example.com/org/app:v1.0.0
31- rkt run example.com/org/app,version=v1.0.0
32
33To support this UX the OCI Image Format contains sufficient information to launch the application on the target platform (e.g. command, arguments, environment variables, etc).
34
35## Distributing an OCI Image
36
37The [OCI Distribution Spec Project](https://github.com/opencontainers/distribution-spec/) defines an API protocol to facilitate and standardize the distribution of content.
38This API includes support for pushing and pulling OCI images to an OCI conformant registry.
39
40## FAQ
41
42**Q: What happens to AppC or Docker Image Formats?**
43
44A: Existing formats can continue to be a proving ground for technologies, as needed.
45The OCI Image Format project strives to provide a dependable open specification that can be shared between different tools and be evolved for years or decades of compatibility; as the deb and rpm format have.
46
47Find more [FAQ on the OCI site](https://www.opencontainers.org/faq).
48
49## Roadmap
50
51The [GitHub milestones](https://github.com/opencontainers/image-spec/milestones) lay out the path to the future improvements.
52
53## Contributing
54
55Development happens on GitHub for the spec.
56Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
57
58The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
59
60### Discuss your design
61
62The project welcomes submissions, but please let everyone know what you are working on.
63
64Before undertaking a nontrivial change to this specification, send mail to the [mailing list](#mailing-list) to discuss what you plan to do.
65This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits.
66It also guarantees that the design is sound before code is written; a GitHub pull-request is not the place for high-level discussions.
67
68Typos and grammatical errors can go straight to a pull-request.
69When in doubt, start on the [mailing-list](#mailing-list).
70
71### Meetings
72
73Please see the [OCI org repository README](https://github.com/opencontainers/org#meetings) for the most up-to-date information on OCI contributor and maintainer meeting schedules.
74You can also find links to meeting agendas and minutes for all prior meetings.
75
76### Mailing List
77
78You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev).
79
80### IRC
81
82OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]).
83
84### Markdown style
85
86To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
87This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
88For example, this paragraph will span three lines in the Markdown source.
89
90### Git commit
91
92#### Sign your work
93
94The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch.
95The rules are pretty simple: if you can certify the below (from [developercertificate.org](https://developercertificate.org/)):
96
97```text
98Developer Certificate of Origin
99Version 1.1
100
101Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
102660 York Street, Suite 102,
103San Francisco, CA 94110 USA
104
105Everyone is permitted to copy and distribute verbatim copies of this
106license document, but changing it is not allowed.
107
108
109Developer's Certificate of Origin 1.1
110
111By making a contribution to this project, I certify that:
112
113(a) The contribution was created in whole or in part by me and I
114 have the right to submit it under the open source license
115 indicated in the file; or
116
117(b) The contribution is based upon previous work that, to the best
118 of my knowledge, is covered under an appropriate open source
119 license and I have the right under that license to submit that
120 work with modifications, whether created in whole or in part
121 by me, under the same open source license (unless I am
122 permitted to submit under a different license), as indicated
123 in the file; or
124
125(c) The contribution was provided directly to me by some other
126 person who certified (a), (b) or (c) and I have not modified
127 it.
128
129(d) I understand and agree that this project and the contribution
130 are public and that a record of the contribution (including all
131 personal information I submit with it, including my sign-off) is
132 maintained indefinitely and may be redistributed consistent with
133 this project or the open source license(s) involved.
134```
135
136then you just add a line to every git commit message:
137
138```text
139Signed-off-by: Joe Smith <joe@gmail.com>
140```
141
142using your real name (sorry, no pseudonyms or anonymous contributions.)
143
144You can add the sign off when creating the git commit via `git commit -s`.
145
146### Commit Style
147
148Simple house-keeping for clean git history.
149Read more on [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) or the Discussion section of [`git-commit(1)`](https://git-scm.com/docs/git-commit).
150
1511. Separate the subject from body with a blank line
1522. Limit the subject line to 50 characters
1533. Capitalize the subject line
1544. Do not end the subject line with a period
1555. Use the imperative mood in the subject line
1566. Wrap the body at 72 characters
1577. Use the body to explain what and why vs. how
158 - If there was important/useful/essential conversation or information, copy or include a reference
1598. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
160
161[code-of-conduct]: https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
162[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/
View as plain text