This page is a wiki; please feel free to contribute, and be bold with your edits!

Adding a mod to the CKAN is simply a matter of writing a small JSON file to describe the mod, its relationship with other mods, and the installation process. If you're releasing on KerbalStuff, or if the mod is packaged in the usual fashion, then the process is even easier!

NOTE TO MOD AUTHORS: You don't need to include the metadata file in your mod: in fact, we advise you not to include it in your package: you should instead submit it to the NetKAN repository. We are happy to receive pull requests!

If you need a hand to write or submit your file, feel free to hop on IRC (#ckan on irc.esper.net) or open a new issue on CKAN-meta and we'll be happy to help you!

You can also check out the forum thread that contains more information and discussion.

It's recommended that you go to the CKAN release page and download the latest ckan.exe. You'll also need the latest netkan.exe, which is periodically updated by our build system. These utilities require a Mono/.NET 4.5 environment (and libcurl on linux/mac) to run, and hence are compatible with Windows, Linux, and Mac!

You will need both ckan.exe and netkan.exe to verify a .netkan file. If you're generating a .ckan file (if the mod isn't hosted by KerbalStuff or GitHub) then you don't need netkan.exe.

Quick Downloads

• ckan.exe
• netkan.exe

If you're doing the work yourself to add the mod to the CKAN: thank you. Here's a straightforward guide to get you on the way:

Step 1. Create the metadata file. Start by finding the guide that matches the hosting solution the mod uses.

• Mods on KerbalStuff can start here
• Mods on GitHub can start here (Mods hosted on both KerbalStuff and GitHub should follow the KerbalStuff guide)
• Mods on neither KerbalStuff nor GitHub can start here

Step 2. Verify the metadata file. See Verifying Metadata Files section

Step 3. Submit the mod to the CKAN repository. See Submitting section

While we love submissions of new CKAN files, it's also completely fine to request a mod be added. If you're the author of said mod, please make sure you mention that. If you know the author is on github, it's polite to tag them in the request when you open it.

Because the mod is hosted on KerbalStuff, once you set up the .netkan file the first time, you'll never need to update it since CKAN can get required information from the KerbalStuff API, including author and latest version.

Copy paste the following into a new file titled <identifier>.netkan (see later for how to choose an identifier):

{
    "spec_version" : 1,
    "identifier"   : "<identifier>",
    "$kref"        : "#/ckan/kerbalstuff/<ksid>",
    "x_netkan_license_ok": true
}

The "spec_version" is the version of the .netkan file language, you should not change this.

You need to change <identifier> to a short, unique, name for the mod that will identify the mod inside the system (end users will not see this name). It must contain only alphanumeric characters (no spaces, no punctuation, no special characters) and it must match the name of the directory that you wish to copy to GameData. Ex: A mod titled "My first ever mod!! I'm so great!$##" that installs to "BestModEver" should have the identifier "BestModEver" because that's where the mod installs to.

This is very important so it will be repeated: the identifier should be the same name as the directory you wish to copy to GameData: if this is not the case, you will need to add more information into the .netkan file in order to tell CKAN where to install files to. See the "Special Installations" section.

The <ksid> should be replaced with the KerbalStuff ID of the mod. This is an integer number and you can find it in the URL of the mod's page:

kerbalstuff.com/mod/<ksid>/YourModName

The "x_netkan_license_ok" relates to the CKAN bots checking KerbalStuff's API for licensing information. There should be no need to change this.

If the mod contains a valid .version file for KSP-AVC see this section

If the mod has "Dependencies or Recommended Companion Mods", see the section with that title, if not you can move on to the Verifying Metadata Files section.

Copy paste the following into a new file titled <identifier>.netkan (see later for how to choose an identifier):

{
    "spec_version" : 1,
    "identifier"   : "<identifier>",
    "$kref"        : "#/ckan/github/<user>/<repo>",
    "name"         : "User-friendly name for the mod",
    "abstract"     : "A short description of what the mod does",
    "license"      : "CC-BY-4.0",
    "ksp_version"  : "1.0.2",
    "resources": {
        "homepage": "<url>"
    }
}

The "spec_version" is the version of the .netkan file language, you should not change this.

You need to change <identifier> to a short, unique, name for the mod that will identify the mod inside the system (end users will not see this name). It must contain only alphanumeric characters (no spaces, no punctuation, no special characters) and it must match the name of the directory that you wish to copy to GameData. Ex: A mod titled "My first ever mod!! I'm so great!$##" that installs to "BestModEver" should have the identifier "BestModEver" because that's where the mod installs to.

This is very important so it will be repeated: the identifier should be the same name as the directory you wish to copy to GameData: if this is not the case, you will need to add more information into the .netkan file in order to tell CKAN where to install files to. See the "Special Installations" section.

You will need to change <user> to the GitHub username, and <repo> to the repository name (Eg: for a mod hosted at https://github.com/pjf/DogeCoinFlag the <user> is pjf and the <repo> is DogeCoinFlag meaning "$kref" should be #/ckan/github/pjf/DogeCoinFlag).

You will need to add the full name you want users to see for the mod under "name" and a description that users will see under "abstract".

You will also have to choose the appropriate license that the mod is under for "license"

Remember, you will have to update the .netkan with the newest ksp_version manually when KSP updates, since Github can't provide us with this information.

Besides when KSP updates though, the mod should remain up to date when new versions of the mod are released.

"resources" conveys extra information to the CKAN clients that users can see. The most useful of which is "homepage" which should be changed to the best source of information regarding the mod (usually the mod's KSP thread)

If the mod contains a valid .version file for KSP-AVC see this section

If the mod has "Dependencies or Recommended Companion Mods", see the section with that title, if not you can move on to the Verifying Metadata Files section.

If the mod uses a hosting solution other than KerbalStuff or Github, it might still be possible to include it in the CKAN as long as the hosting allows automated downloads and you are willing to fill in a little bit of information.

Copy paste the following into a new file titled <identifier>-<version>.ckan (see later for how to choose an identifier):

{
	"spec_version": 1,
  	"identifier"  : "<identifier>",
  	"name"        : "User-friendly name for the mod",
    "author"	  : [ "author1", "author2", "author3" ],
  	"abstract"	  : "A short description of what the mod does",
  	"version"	  : "1.2.3",
	"ksp_version" : "1.0.2",
  	"license"	  : "GPL-3.0",
    "resources": {
        "homepage": "<url>"
    },
  	"download": "<download_url>"
}

Please make sure that automated downloads are possible and allowed by the hosting solution.

The "spec_version" is the version of the .ckan file language, you should not change this.

You need to change <identifier> to a short, unique, name for the mod that will identify the mod inside the system (end users will not see this name). It must contain only alphanumeric characters (no spaces, no punctuation, no special characters) and it must match the name of the directory that you wish to copy to GameData. Ex: A mod titled "My first ever mod!! I'm so great!$##" that installs to "BestModEver" should have the identifier "BestModEver" because that's where the mod installs to.

This is very important so it will be repeated: the identifier should be the same name as the directory you wish to copy to GameData: if this is not the case, you will need to add more information into the .netkan file in order to tell CKAN where to install files to. See the "Special Installations" section.

You will need to add the full name you want users to see for the mod under "name", the author's name under "author" and a description that users will see under "abstract".

Each version of the mod will require manually editing to the new "version" and each update to KSP will require the "ksp_version" to be updated.

You will also have to choose the appropriate license that the mod is under for "license"

"resources" conveys extra information to the CKAN clients that users can see. The most useful of which is "homepage" which should be changed to the best source of information regarding the mod (usually the mod's KSP thread)

Each version of the mod will require manually inputting the "download" location. Simply replace <download_url> with the direct link to the mod's .zip

Our bots will not be able to pick up new releases automatically for these mods. Therefore mods not hosted on KerbalStuff or GitHub should submit the .ckan files to the CKAN-meta repository.

If the mod contains a valid .version file for KSP-AVC see this section

If the mod has "Dependencies or Recommended Companion Mods", see the section with that title.

If everything seems in order, you're ready to verify your .ckan file and you can move on to the Verifying Metadata Files section.

If the distribution contains a valid .version file for KSP-AVC, we can search it for information about which versions of KSP the mod works with. This is done with just one special line:

"$vref" : "#/ckan/ksp-avc"

This is particularly useful for Github (which doesn't natively provide KSP version information) and for KerbalStuff (which doesn't allow for a range of KSP versions to be supported). You should leave out the ksp_version field if you do this.

Dependencies

NOTE TO MOD AUTHORS: While you may bundle your dependencies with your mod for regular users, you should always use an explicit depends relationship rather than getting the CKAN client to install bundled files. Doing so will not only prevent users from upgrading your dependencies, but will also prevent other mods from using them.

If the mod depends on another mod, you can easily tell CKAN by adding just a few lines:

{
    "spec_version" : 1,
    "identifier"   : "<identifier>",
    "$kref"        : "#/ckan/kerbalstuff/<ksid>",

    "depends": [
        { "name": "ModIdentifier" },
        { "name": "FakeMod" },
        { "name": "AwesomeTool"}
    ]
    
}

and that's it! When a user tries to install the mod using CKAN, its dependencies will be also be automatically installed. The CKAN won't install a mod unless it can resolve all the dependencies.

Remember to make sure to specify the CKAN's identifier in the "name" field, or CKAN won't be able to resolve the dependency. You can look at the CKAN-meta repository to find out what mods are supported and find their identifier.

Don't use depends unless you really have to: use them only for things that are absolutely necessary for the mod to function. This means the mod can be installed even if one of the other mods isn't available (which often happens soon after a new KSP release), and gives the user more control over their install.

Recommended and Suggested Companion Mods

You can do exactly the same with recommends and suggests:

• recommends says that modules should be installed with the mod, but they're not absolutely required. These are installed by default unless the user deselects them: use them sparingly!
• suggests indicates these modules are great things to install as well, but won't be installed by default. This should be the preferred method to suggest another mod to the user.

If the mod has some more elaborate installation instructions, you can use an "install stanza" to make sure everything ends up in the right place. The simplest case is when the mod name is different from the directory you need to install; for example, if you group all the mods into a single directory with the author name:

{
    "spec_version" : 1,
    "identifier"   : "<identifier>",
    "$kref"        : "#/ckan/kerbalstuff/<ksid>",

    "install": [
        {
            "file"       : "GameData/MyAuthorName",
            "install_to" : "GameData"
        }
    ]
}

So in this case if a .zip file has a path to the mod of "GameData/MyAuthorName/MyMod" the "MyMod" folder will be installed to the user as "GameData/MyAuthorName/MyMod". In some cases directory structures aren't important. For example if the .zip file has a path to the mod of "hello/world/MyMod" then you would want "file" : "hello/world/MyMod" so that the "MyMod" folder from the zip is installed directly to the "GameData" folder for the user.

You can have multiple install sections, if you need to install multiple parts and have ship files to copy:

    "install": [
        {
            "file"       : "GameData/MyAuthorName/MyMod",
            "install_to" : "GameData",
            "comment"    : "This is the main install for MyMod"
        },
        {
            "file"       : "GameData/TextureReplacer",
            "install_to" : "GameData",
            "comment"    : "This would be TextureReplacer configs for MyMod"
        },
        {
            "file"       : "Extras/Ships",
            "install_to" : "Ships",
            "comment"    : "This would correctly install ships from the mod"
        }
    ]

Please don't use this to install any mods you've bundled in your archive (like ModuleManager). This will cause conflicts. Please use an explicit depends instead (see above section).

The paths are resolved as follows:

• The input path is resolved relative to the packaged zip file: please note that "file" can (and usually does) point to folders.
• The "install_to" path is one of these four special folders:
  • GameData
  • Ships
  • Tutorials
  • GameRoot

Start here if you created a .netkan file (if the mod is hosted on KerbalStuff or GitHub)

You've created the .netkan file, and now you need test to see if it works. You'll be using the netkan.exe utility which will verify the file and generate the metadata for the mod. This is a command-line only program, and you can run it simply by providing the module's name:

netkan.exe --verbose <identifier>.netkan

This will produce a .ckan file (the mod's metadata) in the same directory. You can leave the --verbose switch out, but then the tool will be silent unless something goes wrong.

Having inflated the metadata using the netkan tool, you can try installing the mod:

Start here if you created a .ckan file (if the mod isn't hosted on KerbalStuff or Github)

You can use the ckan GUI to test installing the mod: File -> Install from .ckan

Or the command line:

ckan.exe install -c <identifier>-v1.2.ckan

And you can then view the files installed:

ckan.exe show <identifier>

If that worked, great! The mod is now officially compatible with the CKAN: the next step is submitting

Mods on KerbalStuff and GitHub and created both a .netkan and .ckan: If you've got everything working, then open an issue on the NetKAN and include a copy of the .netkan! If you're familiar with git and github, then we love pull-requests even more!

Mods on neither KerbalStuff nor GitHub and created only a .ckan: If you've got everything working, then open an issue on the CKAN-meta and include a copy of the .ckan! If you're familiar with git and github, then we love pull-requests even more!

Not sure what pull-requests are but want to learn? See the Pull Requests section

If you are still confused, you might be able to solve your problems by taking a look at the metadata files of other mods. The NetKAN has many examples which our indexer uses. If you feel comfortable using git, you can also send us pull requests to this location!

If you need it, the complete CKAN metadata spec is available, in both human readable and machine readable format. The CKAN provides both a lot of power and flexibility, so check out the spec for more things you can do and the ways to use them.

The ckan bots need to run some checks on the file before they can accept it as valid. Unfortunately, this comes with an unpleasant restriction: the file will only be accepted if the license matches one defined in the CKAN schema.

Please choose a license from that list to ensure that the bots can recognize it.

By design, the CKAN does not allow the overwriting of files, nor does it allow installation order to be specified. This not only gives us a number of strong mathematical assurances (we can analyze dependencies as a set, rather than a graph), but it also means we can immediately detect conflicts, and we don't have to worry about mods installed "earlier" in the install overwriting those from "later" in the install when they're upgraded.

The ideal solution (when you can't use ModuleManager) to this is to split configuration from content. TACLS is a great example here; TACLS give you the core, but depends upon the virtual "TACLS-Config" package. That can be provided by TACLS-Config-Stock, or TACLS-Config-RealismOverhaul, which both conflict and provide TACLS-Config, which means that you can only have one installed at a time. If you're running RealismOverhaul, then it depends upon TACLS-Config-RealismOverhaul, so you get the right one. And if you're not running RO, then you'll get the stock config, because the RO config depends upon RO.

Note that this makes it absolutely clear which package owns which files. If you were to upgrade TACLS, you'd still keep the RealismOverhaul configs for it if they were installed.

Of course, the module authors needn't split their configuration from their content at all; instead our metadata documents specify the TACLS config file that comes with TACLS for "Stock", and the one that comes with RealismOverhaul for RO. No extra files are downloaded, but the end result is we still have strong assurances as to file ownership and consistency.

If you need a hand to write or submit the file, feel free to hop on IRC (#ckan on irc.esper.net) or open a new issue on CKAN-meta and we'll be happy to help you!

You can also check out the forum thread that contains more information and discussion.

KerbalStuff and GitHub-hosted mods will upload .netkan files to /KSP-CKAN/NetKAN while mods hosted elsewhere will upload .ckan files to /KSP-CKAN/CKAN-meta -- this example will use a .netkan example (a .ckan will just change the relevant parts).

Submitting files via pull requests makes things a little easier on our end. Here's the easiest way to submit one simply using a web browser.

Step 1: Sign up for a GitHub account and then be logged in.

Step 2: Navigate over to KSP-CKAN's NETKAN repository (or just click).

Step 3: Click on the "NetKAN" folder and you'll see the .netkan files for a large number of mods(or just click).

Step 4: Click the + (plus) icon near the top of the page above the list of files. To help find it, there's a box marked "branch: master" and next that: "NetKAN / NetKAN / +" Or here's an image: http://imgur.com/jsEjOSf

Step 5: At the top insert the file name (example.netkan) then copy + paste the contents of the .netkan file you created earlier into the text box. Click on "Propose new file".

Step 6: Smile. Someone will accept the file into the database and the mod will become listed in CKAN.

What's happening on the backend/more technical stuff? When you clicked on the + link, GitHub created a copy of the entire NetKAN repository under your name. The file you created (the .netkan file) not exists in your copy of the NetKAN repository. The "pull request" is you sending the CKAN team a request for them to take the .netkan file you created and incorporate it into the original repository. Why so complicated? For science!