themis docs deployment deployment_strategy

ThemisDB Build & Deployment Strategy

Overview

ThemisDB v1.0.0 follows a comprehensive multi-platform deployment strategy with automated CI/CD pipelines for Docker Hub, GitHub Releases, and package repositories.

Build Platforms

Supported Platforms

Platform	Architecture	Package Format	Build Method
Linux	x86_64	ZIP, .deb	Docker + dpkg-deb
Linux	x86_64	.rpm	Docker + rpmbuild
QNAP NAS	x86_64	ZIP, Docker	Docker build
Windows	x86_64	ZIP	MSVC 2022 (native)
Docker	x86_64	Container	Docker buildx

Future Platforms (Planned)

• Raspberry Pi (ARM64): .deb packages
• macOS (x86_64 + ARM64): .dmg or Homebrew
• FreeBSD (x86_64): pkg

Build Matrix

Docker Images

Docker Hub Repository: themisdb/themisdb

Tags:
  - latest              # Latest stable release
  - 1.0.0              # Specific version
  - 1.0                # Minor version
  - 1                  # Major version
  - qnap               # QNAP-optimized latest
  - 1.0.0-qnap         # QNAP-specific version

Binary Packages

release/
├── themisdb-1.0.0-linux-x64.zip       # Linux x86_64 binary
├── themisdb-1.0.0-qnap-x64.zip        # QNAP x86_64 binary
├── themis-1.0.0-windows-x64.zip       # Windows x86_64 binary
├── themisdb_1.0.0_amd64.deb           # Debian/Ubuntu package
├── themisdb-1.0.0-1.x86_64.rpm        # RHEL/CentOS/Fedora package
├── SHA256SUMS.txt                     # Checksums for all packages
└── SHA256SUMS_ARCHIVES.txt            # Additional checksums

Build Process

1. Docker Image Build

Script: docker-build-push.ps1

# Build multi-platform images
docker buildx build --platform linux/amd64 \
  --tag themisdb/themisdb:1.0.0 \
  --tag themisdb/themisdb:latest \
  --push .

# QNAP-specific build
docker buildx build --platform linux/amd64 \
  --file Dockerfile \
  --tag themisdb/themisdb:1.0.0-qnap \
  --tag themisdb/themisdb:qnap \
  --push .

Build Time: ~15-20 minutes per platform

Dependencies:

• Docker Desktop with buildx
• Docker Hub credentials (docker login)

2. Linux Binary Extraction

Process:

1. Run Docker container from built image
2. Extract /usr/local/bin/themis_server via docker cp
3. Package with documentation and config files
4. Create ZIP archive
5. Generate SHA256 checksum

Output:

• themisdb-1.0.0-linux-x64.zip (10.24 MB)
• themisdb-1.0.0-qnap-x64.zip (10.01 MB)

3. Debian Package Build

Script: build-deb.sh

Process:

# WSL/Ubuntu environment required
cd /mnt/c/VCC/themis
./build-deb.sh

Package Structure:

themisdb_1.0.0_amd64/
├── DEBIAN/
│   ├── control          # Package metadata
│   ├── postinst         # Post-installation script
│   └── prerm            # Pre-removal script
├── usr/local/bin/
│   └── themis_server    # Main binary
├── lib/systemd/system/
│   └── themisdb.service # Systemd unit
├── etc/themisdb/
│   └── config.json      # Default configuration
└── usr/share/doc/themisdb/
    ├── README.md
    └── LICENSE

Build Time: ~5 minutes

Dependencies:

• WSL2 with Ubuntu
• dpkg-deb
• Proper file permissions (755 for DEBIAN/, 644 for control)

4. RPM Package Build

Script: build-rpm.sh

Process:

# WSL/Ubuntu with rpm tools
sudo apt-get install rpm
cd /mnt/c/VCC/themis
./build-rpm.sh

Spec File: themisdb.spec

Build Time: ~5 minutes

Dependencies:

• rpmbuild
• rpm tools

5. Windows Native Build

Process:

# Visual Studio 2022 (MSVC) build
cmake -B build-msvc -G "Visual Studio 17 2022" -A x64 `
  -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake `
  -DCMAKE_BUILD_TYPE=Release

cmake --build build-msvc --config Release

# Package creation
$binaryPath = "build-msvc\Release\themis_server.exe"
# Copy to release/windows_x64/
# Create ZIP archive

Build Time: ~20-30 minutes (first build with vcpkg)

Dependencies:

• Visual Studio 2022
• vcpkg
• CMake 3.20+

Deployment Targets

1. Docker Hub

Repository: https://hub.docker.com/r/themisdb/themisdb

Deployment Method:

• Automated via docker-build-push.ps1
• Manual push with docker push

Tags Strategy:

• latest - Always points to newest stable release
• X.Y.Z - Immutable version tag
• X.Y - Points to latest patch version
• X - Points to latest minor version
• qnap - Latest QNAP-optimized build

Update Frequency: On each release

2. GitHub Releases

URL: https://github.com/makr-code/ThemisDB/releases

Assets per Release:

• Source code (ZIP + tar.gz) - auto-generated by GitHub
• Binary packages (5 files):
  • Linux x64 ZIP
  • QNAP x64 ZIP
  • Windows x64 ZIP
  • Debian .deb
  • RPM .rpm
• Checksums: SHA256SUMS.txt
• Release notes: RELEASE_NOTES_v1.0.0.md

Deployment Method:

• Manual via GitHub UI or API
• Future: Automated via GitHub Actions

3. Package Repositories (Future)

Debian/Ubuntu Repository

# Add ThemisDB repository
echo "deb https://repo.themisdb.org/debian stable main" | \
  sudo tee /etc/apt/sources.list.d/themisdb.list

# Install
sudo apt update
sudo apt install themisdb

RPM Repository (RHEL/CentOS/Fedora)

# Add ThemisDB repository
sudo tee /etc/yum.repos.d/themisdb.repo <<EOF
[themisdb]
name=ThemisDB Repository
baseurl=https://repo.themisdb.org/rpm/el\$releasever/\$basearch
enabled=1
gpgcheck=1
gpgkey=https://repo.themisdb.org/rpm/RPM-GPG-KEY-themisdb
EOF

# Install
sudo yum install themisdb

Chocolatey (Windows)

choco install themisdb

Homebrew (macOS)

brew install themisdb

CI/CD Pipeline

GitHub Actions Workflow

File: .github/workflows/release.yml

name: Build and Release

on:
  push:
    tags:
      - 'v*.*.*'
  workflow_dispatch:

jobs:
  # Job 1: Build Docker Images
  docker-build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Build and push Linux image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64
          push: true
          tags: |
            themisdb/themisdb:${{ steps.version.outputs.VERSION }}
            themisdb/themisdb:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max
      
      - name: Build and push QNAP image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64
          push: true
          tags: |
            themisdb/themisdb:${{ steps.version.outputs.VERSION }}-qnap
            themisdb/themisdb:qnap
          cache-from: type=gha
          cache-to: type=gha,mode=max

  # Job 2: Extract Linux Binaries
  linux-binaries:
    runs-on: ubuntu-latest
    needs: docker-build
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Pull Docker image
        run: docker pull themisdb/themisdb:${{ steps.version.outputs.VERSION }}
      
      - name: Extract Linux binary
        run: |
          docker create --name temp themisdb/themisdb:${{ steps.version.outputs.VERSION }}
          docker cp temp:/usr/local/bin/themis_server ./themis_server_linux
          docker rm temp
      
      - name: Package Linux ZIP
        run: |
          mkdir -p themisdb-${{ steps.version.outputs.VERSION }}-linux-x64
          cp themis_server_linux themisdb-${{ steps.version.outputs.VERSION }}-linux-x64/themis_server
          cp README.md LICENSE themisdb-${{ steps.version.outputs.VERSION }}-linux-x64/
          cp -r config themisdb-${{ steps.version.outputs.VERSION }}-linux-x64/
          zip -r themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip \
               themisdb-${{ steps.version.outputs.VERSION }}-linux-x64
      
      - name: Generate checksum
        run: |
          sha256sum themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip > \
            themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip.sha256
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: linux-x64-binary
          path: |
            themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip
            themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip.sha256

  # Job 3: Build Debian Package
  debian-package:
    runs-on: ubuntu-latest
    needs: docker-build
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Install dependencies
        run: sudo apt-get update && sudo apt-get install -y dpkg-dev
      
      - name: Pull Docker image
        run: docker pull themisdb/themisdb:${{ steps.version.outputs.VERSION }}
      
      - name: Extract binary
        run: |
          docker create --name temp themisdb/themisdb:${{ steps.version.outputs.VERSION }}
          docker cp temp:/usr/local/bin/themis_server ./themis_server
          docker rm temp
          chmod +x themis_server
      
      - name: Build Debian package
        run: |
          chmod +x build-deb.sh
          ./build-deb.sh
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: debian-package
          path: release/themisdb_*.deb

  # Job 4: Build RPM Package
  rpm-package:
    runs-on: ubuntu-latest
    needs: docker-build
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Install RPM tools
        run: sudo apt-get update && sudo apt-get install -y rpm
      
      - name: Pull Docker image
        run: docker pull themisdb/themisdb:${{ steps.version.outputs.VERSION }}
      
      - name: Extract binary
        run: |
          docker create --name temp themisdb/themisdb:${{ steps.version.outputs.VERSION }}
          docker cp temp:/usr/local/bin/themis_server ./themis_server
          docker rm temp
          chmod +x themis_server
      
      - name: Build RPM package
        run: |
          chmod +x build-rpm.sh
          ./build-rpm.sh
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: rpm-package
          path: release/themisdb-*.rpm

  # Job 5: Build Windows Binary
  windows-binary:
    runs-on: windows-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        shell: pwsh
        run: |
          $version = "${{ github.ref }}".Replace('refs/tags/v', '')
          echo "VERSION=$version" >> $env:GITHUB_OUTPUT
      
      - name: Setup vcpkg
        run: |
          git clone https://github.com/Microsoft/vcpkg.git
          .\vcpkg\bootstrap-vcpkg.bat
      
      - name: Install dependencies
        run: |
          .\vcpkg\vcpkg install --triplet x64-windows
      
      - name: Configure CMake
        run: |
          cmake -B build-msvc -G "Visual Studio 17 2022" -A x64 `
            -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake `
            -DCMAKE_BUILD_TYPE=Release
      
      - name: Build
        run: cmake --build build-msvc --config Release
      
      - name: Package
        shell: pwsh
        run: |
          $version = "${{ steps.version.outputs.VERSION }}"
          $pkgDir = "themis-$version-windows-x64"
          New-Item -ItemType Directory -Path $pkgDir
          
          Copy-Item build-msvc\Release\themis_server.exe $pkgDir\
          Copy-Item README.md, LICENSE $pkgDir\
          Copy-Item -Recurse config $pkgDir\
          
          Compress-Archive -Path $pkgDir -DestinationPath "$pkgDir.zip"
      
      - name: Generate checksum
        shell: pwsh
        run: |
          $version = "${{ steps.version.outputs.VERSION }}"
          $hash = (Get-FileHash "themis-$version-windows-x64.zip" -Algorithm SHA256).Hash
          "$hash  themis-$version-windows-x64.zip" | Out-File "themis-$version-windows-x64.zip.sha256"
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: windows-x64-binary
          path: |
            themis-${{ steps.version.outputs.VERSION }}-windows-x64.zip
            themis-${{ steps.version.outputs.VERSION }}-windows-x64.zip.sha256

  # Job 6: Create GitHub Release
  create-release:
    runs-on: ubuntu-latest
    needs: [linux-binaries, debian-package, rpm-package, windows-binary]
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Download all artifacts
        uses: actions/download-artifact@v4
      
      - name: Generate SHA256SUMS
        run: |
          cd linux-x64-binary && sha256sum *.zip >> ../SHA256SUMS.txt && cd ..
          cd debian-package && sha256sum *.deb >> ../SHA256SUMS.txt && cd ..
          cd rpm-package && sha256sum *.rpm >> ../SHA256SUMS.txt && cd ..
          cd windows-x64-binary && sha256sum *.zip >> ../SHA256SUMS.txt && cd ..
      
      - name: Create release notes
        run: |
          cat > RELEASE_NOTES.md <<EOF
          # ThemisDB v${{ steps.version.outputs.VERSION }}
          
          ## Download
          
          ### Docker
          \`\`\`bash
          docker pull themisdb/themisdb:${{ steps.version.outputs.VERSION }}
          \`\`\`
          
          ### Binary Packages
          - Linux x64: themisdb-${{ steps.version.outputs.VERSION }}-linux-x64.zip
          - Windows x64: themis-${{ steps.version.outputs.VERSION }}-windows-x64.zip
          - Debian/Ubuntu: themisdb_${{ steps.version.outputs.VERSION }}_amd64.deb
          - RHEL/CentOS: themisdb-${{ steps.version.outputs.VERSION }}-1.x86_64.rpm
          
          ## Checksums
          See SHA256SUMS.txt for package verification.
          
          ## Documentation
          https://github.com/makr-code/ThemisDB/blob/main/RELEASE_NOTES_v${{ steps.version.outputs.VERSION }}.md
          EOF
      
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          name: Release v${{ steps.version.outputs.VERSION }}
          body_path: RELEASE_NOTES.md
          draft: false
          prerelease: false
          files: |
            SHA256SUMS.txt
            linux-x64-binary/*.zip
            debian-package/*.deb
            rpm-package/*.rpm
            windows-x64-binary/*.zip
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # Job 7: Update VERSION.json
  update-version-manifest:
    runs-on: ubuntu-latest
    needs: create-release
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Extract version
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
      
      - name: Download artifacts for checksums
        uses: actions/download-artifact@v4
      
      - name: Update VERSION.json
        run: |
          VERSION="${{ steps.version.outputs.VERSION }}"
          DATE=$(date -u +"%Y-%m-%d")
          
          # Calculate checksums
          LINUX_SHA256=$(sha256sum linux-x64-binary/*.zip | cut -d' ' -f1)
          DEB_SHA256=$(sha256sum debian-package/*.deb | cut -d' ' -f1)
          RPM_SHA256=$(sha256sum rpm-package/*.rpm | cut -d' ' -f1)
          WIN_SHA256=$(sha256sum windows-x64-binary/*.zip | cut -d' ' -f1)
          
          # Update VERSION.json
          cat > docs/VERSION.json <<EOF
          {
            "version": "$VERSION",
            "release_date": "$DATE",
            "latest": "$VERSION",
            "channel": "stable",
            "downloads": {
              "linux_x64_zip": {
                "url": "https://github.com/makr-code/ThemisDB/releases/download/v$VERSION/themisdb-$VERSION-linux-x64.zip",
                "sha256": "$LINUX_SHA256",
                "size": $(stat -c%s linux-x64-binary/*.zip)
              },
              "debian_amd64": {
                "url": "https://github.com/makr-code/ThemisDB/releases/download/v$VERSION/themisdb_${VERSION}_amd64.deb",
                "sha256": "$DEB_SHA256",
                "size": $(stat -c%s debian-package/*.deb)
              },
              "rhel_x86_64": {
                "url": "https://github.com/makr-code/ThemisDB/releases/download/v$VERSION/themisdb-$VERSION-1.x86_64.rpm",
                "sha256": "$RPM_SHA256",
                "size": $(stat -c%s rpm-package/*.rpm)
              },
              "windows_x64_zip": {
                "url": "https://github.com/makr-code/ThemisDB/releases/download/v$VERSION/themis-$VERSION-windows-x64.zip",
                "sha256": "$WIN_SHA256",
                "size": $(stat -c%s windows-x64-binary/*.zip)
              },
              "docker": {
                "image": "themisdb/themisdb",
                "tags": ["$VERSION", "latest"]
              }
            },
            "changelog_url": "https://github.com/makr-code/ThemisDB/blob/main/CHANGELOG.md",
            "release_notes_url": "https://github.com/makr-code/ThemisDB/releases/tag/v$VERSION",
            "update_priority": "normal",
            "breaking_changes": false
          }
          EOF
      
      - name: Commit VERSION.json
        run: |
          git config user.name "GitHub Actions"
          git config user.email "[email protected]"
          git add docs/VERSION.json
          git commit -m "Update VERSION.json for v${{ steps.version.outputs.VERSION }}"
          git push origin main

Release Checklist

Pre-Release

• Update VERSION file to new version (e.g., 1.1.0)
• Update CHANGELOG.md with release notes
• Update docs/VERSION.json template
• Run all tests locally
• Build and test all packages locally
• Update documentation if needed

Release Process

1. Create Git Tag

   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin v1.0.0

2. Automated CI/CD Pipeline

   • GitHub Actions workflow triggers on tag push
   • Builds Docker images → Docker Hub
   • Extracts binaries → ZIP packages
   • Builds Debian package
   • Builds RPM package
   • Builds Windows binary
   • Creates GitHub Release with all assets
   • Updates docs/VERSION.json

3. Manual Steps (until fully automated)

   • Run docker-build-push.ps1 for Docker Hub
   • Run Windows build with MSVC
   • Run build-deb.sh in WSL
   • Run build-rpm.sh in WSL
   • Upload assets to GitHub Release
   • Update release notes

Post-Release

• Verify Docker images on Docker Hub
• Test installation from all package formats
• Update main documentation website
• Announce release (blog, social media, forums)
• Monitor for issues

Rollback Strategy

Docker Hub

# Revert latest tag to previous version
docker pull themisdb/themisdb:1.0.0
docker tag themisdb/themisdb:1.0.0 themisdb/themisdb:latest
docker push themisdb/themisdb:latest

GitHub Release

• Mark release as pre-release
• Create new patch release with fixes
• Update VERSION.json to point to stable version

Package Repositories

• Remove broken packages from repositories
• Notify users via mailing list/announcements

Versioning Strategy

Semantic Versioning (semver)

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Examples:
- 1.0.0          # Stable release
- 1.1.0          # New features (backward compatible)
- 1.1.1          # Bug fixes
- 2.0.0          # Breaking changes
- 1.2.0-beta.1   # Beta release
- 1.2.0-rc.1     # Release candidate

Version Bumping Rules

• MAJOR: Breaking API changes, major architectural changes
• MINOR: New features, backward-compatible changes
• PATCH: Bug fixes, security patches, performance improvements

Pre-release Tags

• alpha - Early development, unstable
• beta - Feature complete, testing phase
• rc - Release candidate, final testing

Security

Package Signing

GPG Signing (Future)

# Sign packages
gpg --detach-sign --armor themisdb_1.0.0_amd64.deb
gpg --detach-sign --armor themisdb-1.0.0-1.x86_64.rpm

Checksums

• SHA256 checksums for all packages
• Published in SHA256SUMS.txt
• Automated verification in installation scripts

Docker Image Security

• Multi-stage builds to minimize attack surface
• Non-root user execution
• Regular base image updates
• Vulnerability scanning with Trivy

Monitoring

Build Monitoring

• GitHub Actions status badges
• Build time tracking
• Failure notifications via email/Slack

Deployment Monitoring

• Docker Hub pull statistics
• GitHub Release download counts
• Package repository analytics

Update Checking

• ThemisDB Update Checker subsystem
• Periodic version checks against docs/VERSION.json
• Admin notifications for new releases

Related Documentation

• Packaging Guide
• Update Checker
• Release Notes
• Docker Guide