Installation

Prerequisites

Before installing Divekit, ensure your system meets the following requirements:

System Requirements

• Operating System: Linux, macOS, or Windows
• GitLab: Access to a GitLab instance with API permissions

GitLab Setup

1. Access to a GitLab instance
2. Admin rights to create groups and repositories
3. Personal Access Token with api scope

Creating a Personal Access Token

1. Create one here

or

1. Navigate to your GitLab profile settings
2. Go to “Access Tokens”
3. Create a new token with required scopes
4. Save the token securely - you’ll need it during installation

Storage Requirements

• Minimum 1GB free disk space
• Additional space for repositories (varies by project size)

Network Requirements

• Stable internet connection
• Access to GitLab API endpoints
• No blocking firewalls for HTTP requests

Optional Requirements

• Docker: For running tests in containers
• Maven/Gradle: For Java project support
• IDE: Any Git-compatible IDE for development
• Java: Version 11 or higher (only required for UMLet diagram processing)

Installation

1. Download the latest release:

   • Navigate to Divekit CLI Releases
   • Download a built version for your operating system

2. Install Divekit:
   Navigate to the download directory and run the installation script:

./divekit.exe install  # On Windows
./divekit install      # On Linux/macOS

Environment Setup

After installation, configure your GitLab hosts and tokens using the divekit config command. Tokens are stored securely in your operating system’s credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service).

The DIVEKIT_MEMBERS environment variable is optional for the path for your members files.

GitLab Host and Token Configuration

Use divekit config set @hosts to add your GitLab instance(s). This records the host configuration in ~/.divekit/hosts.json and stores the token in the OS credential manager.

Steps

1. Create a Personal Access Token (if not already done):

   • Go to your GitLab profile > Access Tokens.
   • Create a token with api scope.
   • Copy the token.

2. Add the Host:

   # Simplified syntax with automatic token prompt
   divekit config set @hosts git-nrw https://gitlab.git.nrw/
   
   # Or with direct token (for non-interactive use)
   divekit config set @hosts git-nrw https://gitlab.git.nrw/ --token glpat-xxx...
   
   # Traditional syntax
   divekit config set @hosts.git-nrw.host https://gitlab.git.nrw/
   divekit config set @hosts.git-nrw.token glpat-xxx...
   

   The token is prompted if not provided and stored in the OS credential manager.

3. Verify:

   divekit config get @hosts.git-nrw
   

   Output:

   Host: https://gitlab.git.nrw/
   Token: [stored]
   

Multiple Hosts

Add additional instances:

divekit config set @hosts gitlab-com https://gitlab.com/ --token glpat-yyy...

Member List Configuration

• DIVEKIT_MEMBERS: Optional environment variable for the default path to members.json.

  Set it as a system environment variable:

  Linux/macOS

  Add to ~/.bashrc or ~/.zshrc:

  export DIVEKIT_MEMBERS="/path/to/members.json"
  

  Then:

  source ~/.zshrc
  

  Windows

  Add via System Properties > Environment Variables > User Variables:

  • Variable name: DIVEKIT_MEMBERS
  • Variable value: C:\path\to\members.json

  Alternatively, set per-distribution:

  divekit config set @origin.my-distribution.members.path "/path/to/members.json"
  

Security Notes

• Tokens are stored in the operating system’s credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). ~/.divekit/hosts.json stores only host metadata and a token key reference.
• Restrict permissions:

  chmod 600 ~/.divekit/hosts.json  # Linux/macOS
  

• Use minimal scopes (api for full access, read_api for read-only).
• For CI/CD, use temporary tokens or pipeline variables (override with GITLAB_TOKEN env var).
• hosts.json is ignored in .gitignore by default.
• Avoid .env files for tokens; use config instead.

Verify Installation

Run the doctor command to verify your setup:

divekit doctor

This will check if:

• Divekit is properly installed
• Required environment variables are set
• System requirements are met

Troubleshooting

If you encounter any issues:

1. Run divekit doctor for detailed diagnostics
2. Verify host configuration: divekit config get @hosts
3. Check tokens in the OS keychain:
   • macOS: Keychain Access app > Search for “divekit-cli”
   • Windows: Credential Manager > Windows Credentials > Search for “divekit-cli”
   • Linux: secret-tool search divekit-cli <hostname>
4. Check logs in ~/.divekit/logs
5. Ensure correct permissions for ~/.divekit/ directory (chmod 700 ~/.divekit on Linux/macOS)