Getting Started With Root Libraries

1) Python (pip)

This quick start uses pip for simplicity. Root also supports uv and Poetry (see the Root UI for those configurations).

Environment setup

Always start with a virtual environment:

python3 -m venv venv
source venv/bin/activate

Configure pip to use Root first

Use the exact pip configuration snippet from the Root UI (it’s org/project-specific). The typical pattern is:

• index-url → Root (checked first)
• extra-index-url → PyPI (fallback)

Example (replace the URL with the one provided in the UI):

pip config set global.index-url "https://pkg.root.io/<YOUR_PATH>/simple"
pip config set global.extra-index-url "https://pypi.org/simple"

Store credentials (netrc)

If your Root setup uses token-based authentication, one common option is to store credentials in ~/.netrc so your tooling can authenticate to pkg.root.io without embedding a token in commands.

Important: don’t paste tokens directly into echo ... >> ~/.netrc commands unless you’re comfortable with them landing in your shell history. Prefer creating/editing the file directly, or use a method that doesn’t record the secret.

Example entry (replace with your real token value):

machine pkg.root.io login token password <ROOT_TOKEN>

Lock down permissions:

chmod 600 ~/.netrc

Install and patch

1. Create a requirements.txt with pinned versions (example):

   Text

   aiohttp==3.9.1

2. Download the Root patcher binary (use the URL provided by your team / Root documentation):

   Bash

   curl -fsSL "<PATCHER_BINARY_URL>" -o root.io
   chmod +x root.io

3. Run the patcher:

   • Default behavior: dry run
   • To apply changes:
   Bash

   export DRY_RUN=false
   ./root.io

4. Verify:

   • pip list shows the installed packages.
   • Root UI Inventory shows the new libraries populated.

2) JavaScript (npm)

Yarn is supported, but npm is recommended for quick start.

Authenticate npm to Root

Use the exact .npmrc / npm config snippet from the Root UI (it’s org/project-specific). The system should authenticate to Root and prefer Root before falling back to the public registry.

Important:

• Avoid writing secrets to a project-level .npmrc unless you are 100% sure it won’t be committed. If you use --location=project, ensure .npmrc is ignored by git for that repo.
• Don’t paste tokens into a command line if you care about shell history. Prefer prompting for input or using environment variables.

Typical setup (replace values with those from the Root UI):

npm config set registry "https://pkg.root.io/npm/" --location=user

Token-based auth (preferred when supported by your Root setup):

read -s ROOT_TOKEN && echo
npm config set //pkg.root.io/npm/:_authToken "$ROOT_TOKEN" --location=user

If your Root setup requires basic auth instead, the UI will provide the correct format (often username:token encoded). Avoid committing _auth values to source control.

Install dependencies

1. Clear local cache/state if needed:
   • Delete node_modules/ (and package-lock.json if you want a clean lockfile refresh).
2. Update package.json dependencies as needed.
3. Install:

npm install

3) Java (Maven)

Use Root as a Maven repository (and optional mirror) via ~/.m2/settings.xml. Keep tokens out of source control.

Important:

• Don’t commit settings.xml. Store it in your user home directory.
• Treat the token as a password. Don’t paste it into commands or chats; rotate it if it leaks.
• Lock down permissions: chmod 600 ~/.m2/settings.xml.

Example ~/.m2/settings.xml

Use environment-variable interpolation so the token isn’t stored in plain text:

<settings>
  <servers>
    <server>
      <id>root-io</id>
      <username>rootio</username>
      <password>${env.ROOT_TOKEN}</password>
    </server>
  </servers>

  <mirrors>
    <mirror>
      <id>root-io</id>
      <name>Root Mirror</name>
      <url>https://pkg.root.io/maven/</url>
      <!-- Use "central" to mirror only Maven Central, or "*" to mirror all repositories -->
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

  <profiles>
    <profile>
      <id>root-io</id>
      <repositories>
        <repository>
          <id>root-io</id>
          <url>https://pkg.root.io/maven/</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>root-io</id>
          <url>https://pkg.root.io/maven/</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>root-io</activeProfile>
  </activeProfiles>
</settings>

Usage

1. Export your token for the current shell session:

   Bash

   export ROOT_TOKEN="PASTE_TOKEN_HERE"

2. Run Maven as usual (example):

   Bash

   mvn -v
   mvn -U test

If your organization requires a different <mirrorOf> scope or repository IDs, use the exact configuration provided in the Root UI.