Host a static index yourself

This guide is the single-maintainer way to run a private Sysand index: you add projects with sysand index add and put the result where it is served. See Host a private index for how this option compares to the alternatives.

The main walkthrough runs everything on your local machine. Hosting the index files on GitHub or GitLab instead of your own server is described at the end.

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.

Create local index

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

$ sysand index init
    Creating index

Add a project to the index

You add projects to the index as KPAR files: the package archive that sysand build produces. If you do not have one yet, build it from your project (see Creating your first project):

$ sysand build
    Building kpar `/home/alice/my-project/output/my_project-0.0.1.kpar`

Note that the KPAR filename normalizes characters such as hyphens and spaces in the project name to underscores.

Then, from the index directory, add the KPAR at the path sysand build printed (provided the .project.json inside the KPAR has a publisher field):

$ sysand index add --kpar-path /home/alice/my-project/output/my_project-0.0.1.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 my_project-0.0.1.kpar. The IRI can be freely chosen, but avoid IRIs that could point to another resource, like the ones starting with http(s), file or ssh, and note that a pkg:sysand/<publisher>/<name> IRI can only be chosen for projects which specify publisher in .project.json. See publisher in the metadata reference for what the field means.

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
      Adding usage: `pkg:sysand/my-publisher/my-project`
    Creating env
     Syncing env
  Installing `pkg:sysand/my-publisher/my-project` 0.0.1

If you instead see no resolver was able to resolve the IRI, check that the server is still running and that the publisher and project spelling match what you added to the index.

To stop using sysand.com entirely, use --default-index http://localhost:8080 instead; see Configure a different default index for how to make that permanent. See Indexes for how indexes are combined.

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 and GitLab

As an alternative to running your own server, a forge you already use can serve the index files: a private GitHub repository serves them over raw.githubusercontent.com, and a private GitLab project can serve them from a GitLab Pages site, in both cases with access control through the forge’s normal permissions. You maintain the index exactly as above (sysand index init once, then sysand index add for each release) and push the result; consumers authenticate with a forge token (see Authenticate to an index).

Sensmetry’s ready-made GitHub and GitLab example repositories build on this hosting but implement the reviewed team index model; start there if several people publish. For the single-maintainer flow on this page they are still useful as working references for the raw-URL and Pages hosting details.