You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To share your module with other Puppet users, get contributions to your modules, and maintain your module releases, publish your module on the Puppet Forge. The Forge is a community repository of modules, written and contributed by open source Puppet and Puppet Enterprise users.
17
+
To share your module with other Puppet users, get contributions to your modules, and maintain your module releases, publish your module on the Puppet Forge.
18
+
The Forge is a community repository of modules, written and contributed by open source Puppet and Puppet Enterprise users.
31
19
32
20
To publish your module:
33
21
@@ -44,18 +32,26 @@ To publish your module:
44
32
*[Installing modules][installing]: How to install pre-built modules from the Puppet Forge.
45
33
*[Using plugins][plugins]: How to arrange plugins (such as custom facts and custom resource types) in modules and sync them to agent nodes.
46
34
*[Documenting modules][documentation]: How to write good documentation for your modules.
47
-
*[Puppet Development Kit][pdk]: A package of development and testing tools to help you create great modules.
35
+
*[Vox Pupuli Development Kit][devkit]: A package of development and testing tools to help you create great modules.
48
36
49
37
50
-
## Naming your module
38
+
## Naming your module
51
39
52
40
Your module has two names: a short name, like "mysql", and a long name that includes your Forge username, like "puppetlabs-mysql".
53
41
54
-
To upload to the Forge, use the module long name. This name is composed of your Forge username and the short name of your module. For example, the "puppetlabs" user maintains a "mysql" module, which is known to the Forge as "puppetlabs-mysql". Use this long name in your module's `metadata.json` file. This helps disambiguate modules that might have common short names, such as "mysql" or "apache."
42
+
To upload to the Forge, use the module long name.
43
+
This name is composed of your Forge username and the short name of your module.
44
+
For example, the "puppetlabs" user maintains a "mysql" module, which is known to the Forge as "puppetlabs-mysql".
45
+
Use this long name in your module's `metadata.json` file.
46
+
This helps disambiguate modules that might have common short names, such as "mysql" or "apache."
55
47
56
-
However, your module directory on disk must use the short name, without the username prefix. Module directory names cannot contain dashes or periods; only letters, numbers, and underscores. As long as you have the correct long name in your `metadata.json` file, the `puppet module build` command uses the correct names in the correct places.
48
+
However, your module directory on disk must use the short name, without the username prefix.
49
+
Module directory names cannot contain dashes or periods; only letters, numbers, and underscores.
50
+
As long as you have the correct long name in your `metadata.json` file, the `puppet module build` command uses the correct names in the correct places.
51
+
52
+
{% include alert.html type="note" content="Although the Forge expects to receive modules named `username-module`, its web interface presents them as `username/module`.
53
+
Always use the `username-module` style in your metadata files and when issuing commands." %}
57
54
58
-
> **Note**: Although the Forge expects to receive modules named `username-module`, its web interface presents them as `username/module`. Always use the `username-module` style in your metadata files and when issuing commands.
59
55
60
56
Related topics:
61
57
@@ -77,15 +73,21 @@ Before you build your module package for publishing, you'll need to make sure it
77
73
78
74
To do this, you'll exclude unnecessary files from your package or repository, remove or ignore any symlinks your module contains, and make sure your `metadata.json` contains the correct information.
79
75
80
-
>**Note:** In order to successfully publish your module to the Puppet Forge and ensure that everything is rendered correctly, your README, license file, changelog, and metadata.json must be UTF-8 encoded. If you used the Puppet Development Kit (or the deprecated `puppet module generate` command) to create your module, these files are already UTF-8 encoded.
76
+
{% include alert.html type="note" content="In order to successfully publish your module to the Puppet Forge and ensure that everything is rendered correctly, your `README`, license file, changelog, and `metadata.json` must be UTF-8 encoded.
77
+
If you used modern tooling to create your module, these files are already UTF-8 encoded." %}
78
+
81
79
82
80
### Excluding files from the package
83
81
84
-
To exclude certain files from your module build, include them in either a `.gitignore` or a `.pmtignore` file. This is useful for excluding files that are not needed to run the module, such as files generated by spec tests. The ignore file must be in the root directory.
82
+
It can be useful to exclude files that are not needed to run the module, such as files generated by spec tests.
83
+
This can reduce the size of your generated module or reduce user clutter, for example.
84
+
To exclude files, add them to an [ignore file][ignore] in the root directory.
85
+
Files in `.pdkignore` will be excluded from module builds.
86
+
Files in `.gitignore` will be excluded from modules and also from git, unless specifically added.
85
87
86
-
#### .pmtignore example
88
+
#### `.pdkignore` example
87
89
88
-
```
90
+
```text
89
91
import/
90
92
/spec/fixtures/
91
93
.tmp
@@ -101,52 +103,54 @@ junit/
101
103
tmp/
102
104
```
103
105
104
-
The `.pmtignore` file excludes files during `puppet module build` only. For example, you might want spec tests in your source control but not in your module package, so you would list them in `.pmtignore`. To prevent files, such as those in temporary directories, from ever being checked into Git, use `.gitignore`.
106
+
The `.pdkignore` file excludes files during `jig module build` only.
107
+
For example, you might want spec tests in your source control but not in your module package, so you would list them in `.pdkignore`.
108
+
To prevent files, such as those in temporary directories, from ever being checked into Git, use `.gitignore`.
105
109
106
-
If you have both a `.pmtignore` and a `.gitignore` file, the `puppet module` command uses the `.pmtignore` file.
110
+
If you have both a `.pdkignore` and a `.gitignore` file, the `jig module` command uses the `.pdkignore` file.
107
111
108
112
### Removing symlinks from your module
109
113
110
-
Symlinks in modules are unsupported. If your module contains symlinks, either remove them or ignore them before you build your module.
114
+
Symlinks in modules are unsupported.
115
+
If your module contains symlinks, either remove them or ignore them before you build your module.
111
116
112
-
If you try to build a module package that contains symlinks, you will receive the following error:
117
+
{% include alert.html type="warning" content="If you try to build a module package that contains symlinks, you will receive an warning informing you to remove them.
118
+
They will not be included in the module package." %}
113
119
114
-
```
115
-
Warning: Symlinks in modules are unsupported. Please investigate symlink manifests/foo.pp->manifests/init.pp.
116
-
Error: Found symlinks. Symlinks in modules are not allowed, please remove them.
117
-
Error: Try 'puppet help module build' for usage
118
-
```
119
120
120
121
### Adding module metadata in `metadata.json`
121
122
122
123
To publish your module on the Forge, it must contain required metadata in a `metadata.json` file.
123
124
124
-
If you generated your module using the Puppet Development Kit or the deprecated `puppet module generate` command, you'll already have a `metadata.json` file. Check it and make any necessary edits.
125
+
If you generated your module using modern tooling, you'll already have a `metadata.json` file.
126
+
Check it and make any necessary edits.
125
127
126
-
If you assembled your module manually, you must make sure that you have a `metadata.json` file in your module's main directory. For details on writing or editing the `metadata.json` file, see the related topic about module metadata.
128
+
If you assembled your module manually, you must make sure that you have a `metadata.json` file in your module's main directory.
129
+
For details on writing or editing the `metadata.json` file, see the related topic about module metadata.
127
130
128
-
> **Modulefiles**
129
-
>
130
-
> If you maintain older modules, you might find the metadata stored in a Modulefile. Move any metadata contained in the Modulefile to the `metadata.json`. Modulefiles were deprecated in Puppet 3 and removed in Puppet 4. They are now treated like any other text file in the root directory of the module.
131
+
{% include alert.html type="warning" content="If you maintain very old modules, you might find the metadata stored in a `Modulefile`.
132
+
Move any metadata contained in the `Modulefile` to `metadata.json`.
133
+
Modulefiles were deprecated in Puppet 3 and removed in Puppet 4.
134
+
They are now treated like any other text file in the root directory of the module." %}
131
135
132
136
Related topics:
133
137
134
138
*[Module metadata and `metadata.json`][metadata]
135
139
*[Semantic versioning](http://semver.org/)
136
140
137
141
138
-
## Build your module
142
+
## Build your module
139
143
140
144
To upload your module to the Forge, you first must build the module package.
141
145
142
-
1. From the command line, run `puppet module build <MODULE DIRECTORY>`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory.
146
+
1. From the command line in your module's root directory, run `jig build build`. This command generates a `.tar.gz` package and saves it in the module's `pkg/` subdirectory.
built /home/user/modules/mymodule/pkg/examplecorp-mymodule-0.0.1.tar.gz
150
154
```
151
155
152
156
## Upload a module to the Forge
@@ -161,37 +165,9 @@ Your module package should be a compiled `tar.gz` package of 10MB or less.
161
165
162
166
4. On the upload page, click **Choose File** and use the file browser to locate and select the release tarball. Then click **Upload Release**.
163
167
164
-
After a successful upload, your browser should load the new release page of your module, with any errors popping up on the same screen. Your module's README, Changelog,and License files are displayed on your module's Forge page.
165
-
166
-
## Publish to the Forge automatically with Travis CI
167
-
168
-
You can automatically publish new versions of your module to the Forge using Travis CI.
169
-
170
-
First, set up Travis CI for automatic publishing.
171
-
172
-
1. Enable Travis CI for the module repository.
173
-
2. Generate a Travis-encrypted Forge password string. For instructions, see the Travis CI [encryption keys docs](https://docs.travis-ci.com/user/encryption-keys/).
174
-
3. Create a `.travis.yml` file in the module's repository base. This file should have a deployment section that includes your Forge username and the encrypted Forge password, such as:
175
-
176
-
```
177
-
deploy:
178
-
provider: puppetforge
179
-
user: <FORGE_USER>
180
-
password:
181
-
secure: "<ENCRYPTED_FORGE_PASSWORD>"
182
-
on:
183
-
tags: true
184
-
# all_branches is required to use tags
185
-
all_branches: true
186
-
```
187
-
188
-
To publish to the Forge with Travis CI, update your version, tag your repo, and push your commit.
189
-
190
-
1. Update the version number in the module's `metadata.json` file and commit the change to the module repository.
191
-
2. Tag the module repo with the desired version number. For more information about how to do this, see Git docs on [basic tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging).
192
-
3. Push the commit and tag to your Git repository.
168
+
After a successful upload, your browser should load the new release page of your module, with any errors popping up on the same screen.
169
+
Your module's README, Changelog,and License files are displayed on your module's Forge page.
0 commit comments