Release-sonar-migration

deploy-migration.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 #
 # sonar-tools
-# Copyright (C) 2019-2024 Olivier Korach
+# Copyright (C) 2024 Olivier Korach
 # mailto:olivier.korach AT gmail DOT com
 #
 # This program is free software; you can redistribute it and/or
@@ -19,21 +19,20 @@
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 #
 
-build_docs=1
 build_image=1
 release=0
 
 while [ $# -ne 0 ]; do
     case $1 in
-        nodoc)
-            build_docs=0
-            ;;
         nodocker)
             build_image=0
             ;;
         pypi)
             release=1
             ;;
+        dockerhub)
+            release_docker=1
+            ;;
         *)
             ;;
     esac
@@ -51,16 +50,15 @@ if [ "$build_image" == "1" ]; then
     docker build -t sonar-migration:latest -f migration.Dockerfile .
 fi
 
-if [ "$build_docs" == "1" ]; then
-    rm -rf api-doc/build
-    sphinx-build -b html api-doc/source api-doc/build
-fi
-
 # Deploy on pypi.org once released
 if [ "$release" = "1" ]; then
     echo "Confirm release [y/n] ?"
     read -r confirm
     if [ "$confirm" = "y" ]; then
         python3 -m twine upload dist/sonar_migration-*-py3-*.whl
     fi
+fi
+
+if [ "$release_docker" = "1" ]; then
+    docker buildx build --push --platform linux/amd64,linux/arm64 -t olivierkorach/sonar-migration:0.1  -t olivierkorach/sonar-migration:latest -f migration-release.Dockerfile .
 fi

doc/README.sonar-migration.md

@@ -0,0 +1,129 @@
+# sonar-migration
+Command line tool to collect SonarQube data to prepare eventual migration to SonarCloud.
+
+![Downloads](https://img.shields.io/pypi/dm/sonar-migration?color=informational)
+![Python-Versions](https://img.shields.io/pypi/pyversions/sonar-migration)
+![License](https://img.shields.io/pypi/l/sonar-migration?color=informational)
+![Issues](https://img.shields.io/github/issues/okorach/sonar-tools)
+![Stars](https://img.shields.io/github/stars/okorach/sonar-tools?style=social)
+
+[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=okorach_sonar-tools)](https://sonarcloud.io/dashboard?id=okorach_sonar-tools)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=okorach_sonar-tools&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=okorach_sonar-tools)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=okorach_sonar-tools&metric=bugs)](https://sonarcloud.io/dashboard?id=okorach_sonar-tools)
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=okorach_sonar-tools&metric=ncloc)](https://sonarcloud.io/dashboard?id=okorach_sonar-tools)
+
+**DISCLAIMER**: This software is community software.
+
+
+# Requirements and Installation
+- `sonar-migration` requires python 3.8 or higher
+- Installation is based on [pip](https://pypi.org/project/pip/).
+- Online installation.
+  - Run: `python3 -m pip install sonar-migration` (or `python3 -m pip upgrade sonar-migration`)
+  If install does not behave as expected you can try the **pip** `--force-reinstall` option (see **pip** documentation)
+- `sonar-migration` is also available as a docker image. See [Using sonar-migration in Docker](#docker)
+
+
+# Common command line parameters
+
+All tools accept the following common parameters:
+- `-h` : Displays a help and exits
+- `-u` : URL of the SonarQube server. The default is environment variable `$SONAR_HOST_URL`
+or `http://localhost:9000` by default if the environment variable is not set
+- `-t` : Admin user token to invoke the SonarQube APIs, like `squ_83356c9b2db891d45da2a119a29cdc4d03fe654e`.
+The default is environment variable `$SONAR_TOKEN`.
+Using login/password is not possible.
+The user corresponding to the token must have sufficiently elevated permissions to achieve the tool tasks
+- `-f`: Define the output file, if not specified, `migration.<SERVER_ID>.json` is generated
+- `-o` : Organization, for SonarCloud - Ignored if running against a SonarQube instance
+- `-v` : Logging verbosity level (`WARN`, `ÌNFO` or `DEBUG`). The default is `INFO`.
+`ERROR` and above is always active.
+- `-c` or `--clientCert` : Allows to specify an optional client certificate file (as .pem file)
+- `--httpTimeout` : Sets the timeout for HTTP(S) requests to the SonarQube platform
+- `--skipVersionCheck` : `sonar-migration` occasionnally checks on pypi.org if there is a new version of **sonar-migration** available, and output a warning log if that is the case. You can skip this check with this option.
+- `-l <logFile>` : Send logs to **<logFile>**, stdout by default
+
+See common [error exit codes](#exit-codes) at the bottom of this page
+
+## Required Permissions
+
+To export data, `sonar-migration` needs elevated permissions
+
+## Examples
+```
+export SONAR_HOST_URL=https://sonar.acme-corp.com
+export SONAR_TOKEN=squ_83356c9b2db891d45da2a119a29cdc4d03fe654e
+
+# Exports all platform migration data from https://sonar.acme-corp.com in default output file migration.<SERVER_ID>.json
+sonar-migration
+
+# Exports all platform migration data from https://sonar.acme-corp.com in file data.json
+sonar-migration -f data.json
+
+
+```
+
+For more about what is exported and imported by `sonar-config` please see the [sonar-config complete documentation](https://github.com/okorach/sonar-tools/blob/master/doc/sonar-config.md)
+
+# <a name="docker"></a>Using sonar-migration in Docker
+
+`sonar-migration` is available as a docker image. Here is how to use the docker version:
+```
+docker pull olivierkorach/sonar-migration:latest
+
+docker run --rm -w `pwd` -v `pwd`:`pwd` sonar-migration -t $SONAR_TOKEN -u https://sonar.acme.com 
+# After the command the file migratiob.<SERVER_ID>.json should be in the local (pwd) directory
+
+# Alternatively you can pass the SonarQube URL and token as environment variables
+docker run --rm -w `pwd` -v `pwd`:`pwd` -e SONAR_TOKEN=<YOUR_SONAR_TOKEN> -e SONAR_HOST_URL=<YOUR_SONAR_URL> sonar-migration
+
+# If you run sonar-migration on same machine as SonarQube, to help, the URL fragment http://localhost is automatically transformed in http://host.docker.internal, 
+# For instance the 2 commands below have same outcome
+docker run --rm -w `pwd` -v `pwd`:`pwd` sonar-migration -t $SONAR_TOKEN -u http://host.docker.internal:9000
+docker run --rm -w `pwd` -v `pwd`:`pwd` sonar-migration -t $SONAR_TOKEN -u http://localhost:9000
+```
+
+# <a name="exit-codes"></a>Exit codes
+
+When sonar-migration complete successfully they return exit code 0. En case of fatal error the following exit codes may be returned:
+- Code 1: Authentication error (Incorrect token provided)
+- Code 2: Authorization error (provided token has insufficient permissions)
+- Code 3: Other general Sonar API HTTP error
+- Code 4: No token provided
+- Code 5: Non existing project key provided
+- Code 6: -
+- Code 7: Unsupported operation requested (because of SonarQube edition or configuration)
+- Code 8: -
+- Code 9: -
+- Code 10: Incorrect command line arguments
+- Code 11: Global analysis or project analysis token provided (user token needed for sonar-tools)
+- Code 12: HTTP request time-out using the SonarQube API
+- Code 13: -
+- Code 14: Sonar connection error
+- Code 15: Miscellaneous OS errors
+
+
+# What's New - Release notes
+
+# Version 0.1
+
+- First beta release
+
+# License
+
+Copyright (C) 2024 Olivier Korach
+mailto:olivier.korach AT gmail DOT com
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program; if not, write to the Free Software Foundation,
+Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

migration-release.Dockerfile

@@ -0,0 +1,39 @@
+FROM alpine:3.20.3
+LABEL maintainer="[email protected]" 
+ENV IN_DOCKER="Yes"
+
+ARG USERNAME=sonar
+ARG USER_UID=1000
+ARG GROUPNAME=sonar
+
+# Create the user
+RUN addgroup -S ${GROUPNAME} && adduser -u ${USER_UID} -S ${USERNAME} -G ${GROUPNAME}
+
+# Install python/pip
+ENV PYTHONUNBUFFERED=1
+RUN apk add --update --no-cache python3 && ln -sf python3 /usr/bin/python
+
+# create a virtual environment and add it to PATH so that it is 
+# applied for all future RUN and CMD calls
+ENV VIRTUAL_ENV=/opt/venv
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+
+WORKDIR /opt/sonar-migration
+
+COPY ./sonar sonar
+COPY ./requirements.txt .
+COPY ./cli cli
+COPY ./setup_migration.py .
+COPY ./sonar_migration .
+COPY ./README.md .
+COPY ./LICENSE .
+COPY ./sonar/audit sonar/audit
+
+RUN pip install --upgrade pip \
+&& pip install sonar-migration==0.1 --force-reinstall
+
+USER ${USERNAME}
+WORKDIR /home/${USERNAME}
+
+ENTRYPOINT ["sonar-migration"]

migration-snapshot.Dockerfile

@@ -0,0 +1,42 @@
+FROM alpine:3.20.3
+LABEL maintainer="[email protected]" 
+ENV IN_DOCKER="Yes"
+
+ARG USERNAME=sonar
+ARG USER_UID=1000
+ARG GROUPNAME=sonar
+
+# Create the user
+RUN addgroup -S ${GROUPNAME} && adduser -u ${USER_UID} -S ${USERNAME} -G ${GROUPNAME}
+
+# Install python/pip
+ENV PYTHONUNBUFFERED=1
+RUN apk add --update --no-cache python3 && ln -sf python3 /usr/bin/python
+
+# create a virtual environment and add it to PATH so that it is 
+# applied for all future RUN and CMD calls
+ENV VIRTUAL_ENV=/opt/venv
+RUN python3 -m venv ${VIRTUAL_ENV}
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+
+WORKDIR /opt/sonar-migration
+
+COPY ./sonar sonar
+COPY ./requirements.txt .
+COPY ./cli cli
+COPY ./setup_migration.py .
+COPY ./sonar_migration .
+COPY ./README.md .
+COPY ./LICENSE .
+COPY ./sonar/audit sonar/audit
+
+RUN pip install --upgrade pip \
+&& pip install --no-cache-dir -r requirements.txt \
+&& pip install --no-cache-dir --upgrade pip setuptools wheel \
+&& python setup_migration.py bdist_wheel \
+&& pip install dist/sonar_migration-py3-*.whl --force-reinstall
+
+USER ${USERNAME}
+WORKDIR /home/${USERNAME}
+
+ENTRYPOINT ["sonar-migration"]