Configure a different default index#

By default, sysand resolves projects from the Sysand Index at sysand.com. Use this guide when you want sysand to use a different index instead, for example a self-hosted private index (see Host a private index). If you want an extra index in addition to the default one, use the --index option instead; see Indexes for how the two relate and how multiple indexes are ordered.

Prerequisites#

  • sysand is installed.

  • You know the URL of the index you want to use, and it is reachable from your machine.

  • If the index requires authentication, sysand is set up with credentials for it; see Authenticate to an index.

Choose where to configure it#

There are four ways to set the default index, differing in how long the setting lasts and who it affects. Pick the one that matches your situation:

The examples below use https://index.example.org as the index URL; replace it with your index’s URL.

For a single command#

Pass --default-index to any command that resolves projects, such as sysand add:

$ sysand add pkg:sysand/<publisher>/<name> --default-index https://index.example.org

For a shell session or CI job#

Set the SYSAND_DEFAULT_INDEX environment variable. Every sysand command in the same environment then uses that index:

$ export SYSAND_DEFAULT_INDEX=https://index.example.org
$ sysand add pkg:sysand/<publisher>/<name>

In a CI job, set the variable through your CI system’s environment configuration instead of export.

For one project#

Create a sysand.toml file in the project’s root directory (next to .project.json) with an index entry marked default = true:

[[index]]
url = "https://index.example.org"
default = true

Every sysand command run inside the project now uses this index, for you and for anyone else who checks out the project. This is the right place when the project’s dependencies live in a specific index: commit the file alongside the rest of the project.

For everything you run on your machine#

Add the same entry to your user-level configuration file, creating the file and its directory if they do not exist yet:

%APPDATA%\sysand\sysand.toml

~/Library/Application Support/sysand/sysand.toml

~/.config/sysand/sysand.toml

[[index]]
url = "https://index.example.org"
default = true

This applies to every project you work on. A project can still override it with its own sysand.toml; see Configuration for how the files combine.

Verify#

Ask sysand to describe a project that you know exists in the new index. This resolves the project against the index without changing anything locally:

$ sysand info --iri pkg:sysand/<publisher>/<name>
Name: <name>
Publisher: <publisher>
Version: 1.0.0

If you configured the index for a single command or a session, include the option or environment variable in this check too.

If the output shows the project’s metadata, the index is being used. If you instead see no resolver was able to resolve the IRI, work through these checks:

  1. The index is actually in effect: run the command again with -v and look for GET log lines to see which index URLs sysand contacts.

  2. The project: check the publisher and name spelling against what the index actually serves.

  3. The credentials, if the index requires authentication: work through the checks in Authenticate to an index.