Self-hosting a project index

This tutorial shows how to host a private Sysand index — a directory of project files served over HTTP that sysand can install projects from. You will create an index, add a project to it, serve it over HTTP, and install from it with the sysand client.

The main walkthrough runs everything on your local machine. Two ready-made alternatives, GitHub and GitLab, are described at the end.

Note

This guide is only concerned with hosting the project files in the structure that sysand can understand. Hosting a front-end website (such as the Sysand Index at sysand.com) is not a part of this guide.

Warning

Sysand is in active development. The structure of indexes and .sysand folders can and will change with future updates of Sysand. As long as Sysand is on version 0.x.y, we cannot guarantee backwards compatibility between different Sysand versions and indexes created using different Sysand versions.

Local machine

This part of the guide focuses on running a Sysand index on your local machine for testing purposes, but the general approach applies to more sophisticated production hosting as well: any static HTTP server can serve the index files.

The easiest way to host a project index from which to install projects is to create a local Sysand index and expose it over HTTP.

Create local index

First, use sysand to create a Sysand index in your current directory:

$ sysand index init
    Creating index

Add project to the index

You can now add the projects you want to share into the Sysand index. For example, if you have a MyProject.kpar file in your current directory, you can add it to the index (provided the .project.json inside the KPAR has a publisher field):

$ sysand index add --kpar-path MyProject.kpar
      Adding pkg:sysand/my-publisher/my-project version 0.0.1

This creates an entry in the project index with an IRI such as pkg:sysand/my-publisher/my-project that other people can then use to install your project. The IRI uses the normalized publisher and name from .project.json; see Project identifiers for the naming and normalization rules.

Tip

If .project.json does not specify a publisher field, you must provide an IRI as a positional argument, for example sysand index add my:iri/my-project --kpar-path MyProject.kpar. See publisher in the metadata reference for what the field means.

Tip

Any IRI can be freely chosen for the positional IRI argument, just don’t choose an IRI that could point to another resource, like the ones starting with http(s), file or ssh. Also, a pkg:sysand/<publisher>/<name> IRI can only be chosen for projects which specify publisher in .project.json.

Repeat this step for each project version you want to share. All versions of a project use the same IRI.

Yank or remove

You can also yank a project version, remove a project version, or remove the entire project. See yank command and remove command for more details.

Start an HTTP server

Once you have added all the required projects to the index, you can use Python and its built-in http.server module to quickly start a simple HTTP server that makes the project index accessible over the network (this requires Python 3; any static file server works just as well). From the index directory, run:

$ python3 -m http.server 8080
Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...

This command executes the http.server module on port 8080, and tells the module to expose the contents of the current folder to the network.

Important

Python’s built-in http.server module is not intended for production use. For shared or production hosting, any static HTTP server works; your IT team can help pick one.

Sysand client setup

You should now be able to access the project index through http://localhost:8080. To test it, create a new SysML v2 project in another directory by following Creating your first project.

Then, when adding a new usage to the project, use the --index argument to make your private index available in addition to the default sysand.com index, for example:

$ sysand add pkg:sysand/my-publisher/my-project --index http://localhost:8080

To stop using sysand.com entirely, use --default-index http://localhost:8080 instead. See Indexes for how indexes are combined and how to configure them permanently in sysand.toml.

Important

localhost tells Sysand to look for the project index running on your machine. For connecting to other machines replace localhost by the address of the other machine, ensuring that networking and firewalls are correctly configured.

GitHub

As an alternative to running your own server, you can host a Sysand index from a private GitHub repository. This allows you to host an index without needing to set up a server, while also allowing simple access control through GitHub’s access management.

Sensmetry has a public GitHub repository implementing this approach. It is licensed under the Creative Commons Zero license and can be freely forked and used in any setting. The repository README contains a detailed explanation of how to set up such a repository and use it.

GitLab

Similarly, you can host a Sysand index from a private GitLab Pages instance, with access control through GitLab’s access management.

Sensmetry has a public GitLab repository implementing this approach. It is licensed under the Creative Commons Zero license and can be freely forked and used in any setting. The repository README contains a detailed explanation of how to set up such a repository and use it.