Private Satis Repository - CzechGroup

This document describes the setup, configuration, and usage of the CzechGroup private Composer repository based on Satis system.

What is Satis?

Satis is a static Composer repository generator that allows you to create your own private package repository for PHP libraries. In our case, it serves as the distribution platform for internal plugins and libraries across CzechGroup projects.

Web Interface

The Satis repository is accessible at: https://satis.czechgroup.cz

Authentication Credentials

Access to the web interface requires authentication credentials:

• Username: satis-view
• Password: tP5!YvXn!LRVFM

The web interface provides an overview of all available packages, their versions, and basic information.

Adding a Package to Satis

Step 1: GitLab Placement

The package must be located in the GitLab "packages" group - only this group is configured for automatic package collection by Satis.

Step 2: Server Configuration

Connect to the mis04.vas-server.cz server via FTP and navigate to the folder:

czechgroup.cz/satis-conf/

Open the satis.json file and add your new repository:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@gitlab.com:czechgroup/packages/package-name.git",
      "name": "czechgroup/package-name"
    }
  ]
}

Parameters:

• type: Always set to "vcs"
• url: SSH URL of your GitLab repository
• name: Package name (must match the name in composer.json)

Step 3: Configure .gitlab-ci.yml

Create a .gitlab-ci.yml file in the root directory of your package:

variables:
  DEPLOY_USER: "deploy"
  SERVER: "mis04.vas-server.cz"
  PLUGIN_NAME: "czechgroup/package-name"  # ← MUST match composer.json name
  SATIS_FILE: "satis.json"
  PUBLIC_DIR: "../satis/"

stages:
  - setup
  - test
  - build
  - deploy

build:
  stage: build
  tags:
    - deploy
  script:
    - ssh $DEPLOY_USER@$SERVER "cd /www/hosting/czechgroup.cz/satis-conf && php bin/satis build $SATIS_FILE $PUBLIC_DIR $PLUGIN_NAME"

⚠️ Critical: The PLUGIN_NAME variable value MUST be identical to the name value in your package's composer.json file.

Step 4: Package composer.json

Ensure your composer.json contains the correct name:

{
  "name": "czechgroup/package-name",
  "type": "library",
  "license": "proprietary",
  "description": "Package description",
  "require": {
    "php": ">=8.1"
  },
  "autoload": {
    "classmap": ["src/"]
  }
}

Step 5: Publication

After pushing to GitLab, the CI/CD pipeline will automatically:

1. Connect to the mis04.vas-server.cz server
2. Run satis build for the specified package
3. Update the Satis repository

The package is then available for installation via Composer.

Using a Package in Your Project

Step 1: Obtain Access Credentials

Contact the CTO to request:

• Satis username
• Satis password

These credentials are required for authentication when downloading packages.

Step 2: Configure Project composer.json

Add the Satis repository to the repositories section:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://satis.czechgroup.cz"
    }
  ],
  "require": {
    "czechgroup/package-name": "^1.0"
  }
}

Step 3: Install the Package

When you run the installation command, Composer will automatically prompt you for authentication credentials. Simply enter the username and password provided by the CTO.

composer install

or

composer require czechgroup/package-name

Versions and Tags

Use Git tags for proper package versioning:

git tag v1.0.0
git push origin v1.0.0

Satis automatically recognizes tags as package versions. For development, you can also use branch versions (e.g., dev-master).

Troubleshooting

Package Not Appearing in Satis

1. Verify the repository is in the "packages" group in GitLab
2. Check the configuration correctness in satis.json
3. Review the CI/CD pipeline logs in GitLab

Authentication Error During Installation

1. Verify you entered the correct credentials when prompted
2. Ensure you received valid credentials from the CTO
3. Clear Composer cache: composer clear-cache
4. Try the installation again - Composer will re-prompt for credentials

Package Not Updating

1. Ensure a new Git tag was created
2. Verify the CI/CD pipeline ran successfully
3. Clear Composer cache and try again

Security

• Credentials are personal and should not be shared between employees (for credential leakage will always be responsible emplyee whom that credentials belongs to)
• Never store credentials in project files or commit them to the repository
• Composer will prompt for credentials when needed - always enter them interactively
• In case of credential compromise, contact the CTO immediately

Contact

For technical support or access credential requests, contact the CTO.