diff --git a/DC-obs-admin-guide b/DC-obs-admin-guide index 745d18fc..2f0d6afa 100644 --- a/DC-obs-admin-guide +++ b/DC-obs-admin-guide @@ -6,7 +6,7 @@ ## Basics MAIN="MAIN-obs.xml" # See "book-obs-admin-guide.xml" -ROOTID="book.obs-admin" +ROOTID="book-obs-admin" ## Profiling PROFOS="opensuse;novell" @@ -18,8 +18,9 @@ PROFCONDITION="bogus" STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse" -## Use DocBook5 instead of GeekoDoc -DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +### Use GeekoDoc +#DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat" ## Disabled SUSE logo XSLTPARAM="--param generate.logo=0" diff --git a/DC-obs-all b/DC-obs-all index 352b91e4..7962d9e8 100644 --- a/DC-obs-all +++ b/DC-obs-all @@ -16,8 +16,9 @@ PROFCONDITION="bogus" STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse" -## Use DocBook5 instead of GeekoDoc -DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +### Use GeekoDoc +#DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat" ## enable sourcing export DOCCONF=$BASH_SOURCE diff --git a/DC-obs-user-guide b/DC-obs-user-guide index 8982fb13..890aa7c1 100644 --- a/DC-obs-user-guide +++ b/DC-obs-user-guide @@ -6,7 +6,7 @@ ## Basics MAIN="MAIN-obs.xml" # See "book-obs-user-guide.xml" -ROOTID="book.obs-user" +ROOTID="book-obs-user" ## Profiling PROFOS="opensuse;novell" @@ -18,8 +18,9 @@ PROFCONDITION="bogus" STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse" -## Use DocBook5 instead of GeekoDoc -DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +### Use GeekoDoc +#DOCBOOK5_RNG_URI="http://docbook.org/xml/5.2/rng/docbookxi.rng" +DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat" ## Disabled SUSE logo XSLTPARAM="--param generate.logo=0" diff --git a/README.md b/README.md index 33ad6bc5..f6280b2a 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ daps2docker DC-obs-user-guide validate or if you want to preview the HTML files you can use ``` -rm -rf /tmp/daps2docker-*; daps2docker DC-obs-user-guide html; xdg-open /tmp/daps2docker-*/obs-user-guide/html/book.obs-user/index.html +rm -rf /tmp/daps2docker-*; daps2docker DC-obs-user-guide html; xdg-open /tmp/daps2docker-*/obs-user-guide/html/book-obs-user/index.html ``` For more detailed information see diff --git a/xml/MAIN-obs.xml b/xml/MAIN-obs.xml index affe1a03..7db9fce5 100644 --- a/xml/MAIN-obs.xml +++ b/xml/MAIN-obs.xml @@ -7,7 +7,7 @@ %entities; ]> - - diff --git a/xml/art-obs-beginners-guide.xml b/xml/art-obs-beginners-guide.xml index 3a263c5c..27e74ca2 100644 --- a/xml/art-obs-beginners-guide.xml +++ b/xml/art-obs-beginners-guide.xml @@ -14,7 +14,7 @@ https://www.suse.com/communities/blog/open-build-service-create-image-template/ https://www.suse.com/communities/blog/suse-studio-integration/ --> - @@ -31,7 +31,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Target Audience This document is intended for users and developers interested in @@ -42,7 +42,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ toms 2017-08-03: Add some links to basic tutorials etc.? - + Conceptual Overview Created in 2005, the &obs; (&obsa;) is a generic system for building and @@ -53,7 +53,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ (&suse;, Debian, Ubuntu, Red Hat, Windows, etc.) and hardware architectures (&x86;, &amd64;, &zseries;, &ppc; etc.). - + Build Recipe To create a package in &obsa;, you need a build recipe @@ -106,7 +106,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ class="extension">.spec. - + Build Hosts and Packages The &obsa; server provides a Web interface and an API. The API is @@ -139,10 +139,10 @@ https://www.suse.com/communities/blog/suse-studio-integration/ scope of this guide. - The schematic in shows the components + The schematic in shows the components in context. -
+
Conceptual Overview of &obs; @@ -151,7 +151,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/
- + Projects and Packages In &obsa;, packages are organized in projects. @@ -192,14 +192,14 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Requirements for Working with the &osccmd; Command-Line Tool Before you start working with &obs;, make sure that the following requirements are met. - + Software Requirements @@ -249,7 +249,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Covered Scenarios This guide is based on the following assumptions. @@ -276,7 +276,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ You are using a customized system as shown in . + linkend="sec-obsbg-obsconfig"/>. All examples use the following elements. @@ -312,7 +312,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Setting up a home project using the &obsa; Web UI. @@ -320,7 +320,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Creating packages from a basic project hosted on &gh;. @@ -328,7 +328,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Patching source code without touching the original @@ -337,7 +337,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Branching a project, making changes, and submitting back @@ -346,7 +346,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Integrating the download repository into your system @@ -357,7 +357,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Configuring Your System for &obsa; While it is possible to use the &osccmd; tool without any @@ -376,7 +376,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ Follow the steps below to customize sudo. - + Configuring <command>sudo</command> To allow all users in the @@ -389,7 +389,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ This group will contain all users which are allowed to build packages: &prompt.root;groupadd osc - + Add users to your newly created group osc which are allowed to build packages: @@ -443,7 +443,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build - + Setting Up Your Home Project for the First Time This section shows how to set up your home project after @@ -459,7 +459,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build specific package. Setting up a home project is done as shown below. - + Adding Global Build Targets to Your Home Project @@ -512,7 +512,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build toms 2017-08-14: Maybe add a screenshot of the Web UI? - + Creating a New Project This section demonstrates how to create packages from a simple C++ project @@ -545,9 +545,9 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build To create a package from the upstream project, follow the steps below. - + - Set up your project as shown in . + Set up your project as shown in . @@ -571,12 +571,12 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build baseform="Working Directory">working directory: &prompt.user;cd &obsworkdir1; -&prompt.user;osc mkpac &gitproject; +&prompt.user;osc mkpac &sampleprj; Get the source code of the upstream project and save it in - &obsworkdir1;/&gitproject;. + &obsworkdir1;/&sampleprj;. Download a TAR archive of the sources. You do not have to unpack it yet. @@ -600,32 +600,32 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build baseform="Spec File">spec file. The skeleton of such a spec file looks like this: - + Skeleton of a Spec File # -# spec file for package &gitproject; +# spec file for package &sampleprj; # # -- Copyright omitted -- -Name: &gitproject; -Version: &gitprjvers; -Release: 0 -License: GPL-3.0 -Group: Documentation -Summary: Frobnication Tool -Url: &gitupstream1; -Source: &gitproject;-%{version}.tar.gz -BuildRequires: gcc -BuildRequires: cmake +Name: &sampleprj; +Version: &prjvers; +Release: 0 +License: GPL-3.0 +Group: Documentation +Summary: Frobnication Tool +Url: &gitupstream1; +Source: &sampleprj;-%{version}.tar.gz +BuildRequires: gcc +BuildRequires: cmake BuildRoot: %{_tmppath}/%{name}-%{version}-build -%description +%description This tool frobnicates the bar with the foo when choosing the baz. -%prep +%prep %setup -q -n %{name}-%{version} -%build -%install -%files +%files %defattr(-,root,root,-) %doc README LICENSE *.txt %{_bindir}/* -%changelog +%changelog - + The Header Metadata like package name, version, release, @@ -655,7 +655,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + Build Requirements Lists package dependencies that are required for building. @@ -665,25 +665,25 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Description Section Describes the purpose of the package and gives a comprehensive explanation. - + The Preparation Section Prepares the sources for building. This usually includes unpacking them with the %setup macro and patching them using the %patch macro. (For more information about patching, see - .) + .) - + The Build Section @@ -693,7 +693,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Install Section Contains commands or RPM macros which @@ -701,7 +701,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Files Section Lists all files and directories which belong to @@ -711,7 +711,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Changelog Section This section is usually empty. Instead, &obsa; searches for a @@ -725,7 +725,6 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - toms 2017-08-17: FIXME: Better link to OBS instead of GH? For the complete spec file, see . @@ -744,13 +743,13 @@ Fri Aug 23 12:31:41 UTC 2017 - &exampleuser_mail; Save the file and leave the editor. &osccmd; then - creates the file &gitproject;.changes. + creates the file &sampleprj;.changes. Your project directory should now look something like this: project directory - ├── &gitproject;-&gitprjvers;.tar.gz - ├── &gitproject;.changes - └── &gitproject;.spec + ├── &sampleprj;-&prjvers;.tar.gz + ├── &sampleprj;.changes + └── &sampleprj;.spec Add all the files to your working directory: @@ -794,11 +793,11 @@ openSUSE_Tumbleweed x86_64 *.spec--> &prompt.user;osc buildlog openSUSE_Tumbleweed x86_64 - + Patching Source Code This section describes how to patch an upstream project. We use the same - project as shown in . + project as shown in . There are different reasons for patching a package. @@ -854,13 +853,13 @@ openSUSE_Tumbleweed x86_64 *.spec--> We assume that you already have a project as described in - . The project directory should look + . The project directory should look similar to this: project directory -├── &gitproject;-&gitprjvers;.tar.gz -├── &gitproject;.changes -└── &gitproject;.spec +├── &sampleprj;-&prjvers;.tar.gz +├── &sampleprj;.changes +└── &sampleprj;.spec In our case, we want to modify the source code under src/main.cpp to change the greeting message. @@ -874,21 +873,21 @@ openSUSE_Tumbleweed x86_64 *.spec--> Unpack the source code: - &prompt.user;tar xvf &gitproject;-*.tar.gz + &prompt.user;tar xvf &sampleprj;-*.tar.gz If you have downloaded the archive from &gh;, the archive contains a directory in the form NAME-VERSION. In our case, unpacking the downloaded archive results in the - &gitproject;-&gitprjvers;/ directory. + &sampleprj;-&prjvers;/ directory. - Switch to the directory &gitproject;-&gitprjvers;/ + Switch to the directory &sampleprj;-&prjvers;/ and make a copy of the original C++ source file: - &prompt.user;cd &gitproject;-&gitprjvers;/ + &prompt.user;cd &sampleprj;-&prjvers;/ &prompt.user;cp src/main.cpp src/main.cpp.orig @@ -913,7 +912,7 @@ openSUSE_Tumbleweed x86_64 *.spec--> Redirect the diff into a file: &prompt.user;diff -u src/main.cpp.orig src/main.cpp \ - > ../&gitproject;_main.diff + > ../&sampleprj;_main.diff You can use an arbitrary name for the patch file. However, we recommend giving the file a descriptive name and adding the name of the @@ -927,7 +926,7 @@ openSUSE_Tumbleweed x86_64 *.spec--> You can now remove the directory &gitproject;-&gitprjvers;/, as it is not needed anymore. + >&sampleprj;-&prjvers;/, as it is not needed anymore. @@ -935,8 +934,8 @@ openSUSE_Tumbleweed x86_64 *.spec--> Open your spec file and add the following line in the header under the Source line like this: - Source: &gitproject;-%{version}.tar.gz -Patch0: &gitproject;_main.diff + Source: &sampleprj;-%{version}.tar.gz +Patch0: &sampleprj;_main.diff In the %prep section, add the %patch @@ -949,7 +948,7 @@ Patch0: &gitproject;_main.diff Add your patch file to the local repository: - &prompt.user;osc add &gitproject;_main.diff + &prompt.user;osc add &sampleprj;_main.diff @@ -974,7 +973,7 @@ Patch0: &gitproject;_main.diff - + Branching a Package This section describes how to collaborate between projects. @@ -1009,7 +1008,7 @@ Patch0: &gitproject;_main.diff Let us assume that there is a user &obsuser1; - who has created a package &obshome1;/&gitproject; + who has created a package &obshome1;/&sampleprj; on &obsa;. Now, a second user, &obsuser2;, would like to submit a code change request to that package. @@ -1017,7 +1016,7 @@ Patch0: &gitproject;_main.diff User &obsuser2; has to perform the following steps: - + Branching from a Project @@ -1027,19 +1026,19 @@ Patch0: &gitproject;_main.diff Create a branch from &exampleuser_plain;'s home project: - &prompt.user2;osc branchco &obshome1; &gitproject; - This creates a branched package in &obsa; at &obsbranch2;/&gitproject; + &prompt.user2;osc branchco &obshome1; &sampleprj; + This creates a branched package in &obsa; at &obsbranch2;/&sampleprj; and checks out a directory - &obsworkdir2;:branches:home:&obsuser1;:&gitproject;. + &obsworkdir2;:branches:home:&obsuser1;:&sampleprj;. Change the working directory to your checked-out branch: - &prompt.user2;cd &obsworkdir2;/branches/home/&obsuser1;/&gitproject; + &prompt.user2;cd &obsworkdir2;/branches/home/&obsuser1;/&sampleprj; Make changes as shown in . + linkend="sec-obsbg-uc-patching"/>. @@ -1087,7 +1086,7 @@ Patch0: &gitproject;_main.diff be submitted together. To avoid that, specify the names of the source and destination projects and the package name: - &prompt.user2;osc submitreq &obsbranch2;:&obshome1; &gitproject; &obshome1; + &prompt.user2;osc submitreq &obsbranch2;:&obshome1; &sampleprj; &obshome1; @@ -1156,7 +1155,7 @@ Patch0: &gitproject;_main.diff If preferred, the below steps can also be performed using the OBS GUI. Requests can be managed under the Tasks tab. - + Dealing with Submit Requests Show all submit requests that belong to your home project @@ -1197,7 +1196,7 @@ Patch0: &gitproject;_main.diff - + Installing Packages from &obsa; &obsa; provides a place containing all the distribution-specific and @@ -1219,10 +1218,10 @@ Patch0: &gitproject;_main.diff &obsdnlurlhome1;/openSUSE_Tumbleweed. This download repository is used as an installation source for Zypper or &yast;. - To install the &gitproject; package from your home project, + To install the &sampleprj; package from your home project, use the following steps: - + Inside your working directory, determine the download repository URLs: &prompt.user;osc repourls @@ -1233,27 +1232,27 @@ Patch0: &gitproject;_main.diff Copy the desired URL of your preferred distribution. In our case, that is the line containing openSUSE_Tumbleweed. - + Use zypper and add the copied URL: &prompt.root;zypper addrepo &obsdnlurlhome1;/openSUSE_Tumbleweed/&obshome1;.repo When prompted, accept the GPG key of the download repository. - + Install the package: - &prompt.root;zypper install &gitproject; + &prompt.root;zypper install &sampleprj; - To update the package again, run . + To update the package again, run . You do not need to execute - , as the + , as the repository is already configured in your system. - + Other Useful &osccmd; Commands The following list gives you a short overview of frequently used &osccmd; diff --git a/xml/book-obs-admin-guide.xml b/xml/book-obs-admin-guide.xml index 60af1593..b3ed7f34 100644 --- a/xml/book-obs-admin-guide.xml +++ b/xml/book-obs-admin-guide.xml @@ -10,7 +10,7 @@ + xml:id="book-obs-admin"> Administrator Guide &productname; diff --git a/xml/book-obs-user-guide.xml b/xml/book-obs-user-guide.xml index fc6b527a..8b574b59 100644 --- a/xml/book-obs-user-guide.xml +++ b/xml/book-obs-user-guide.xml @@ -7,7 +7,7 @@ %entities; ]> - @@ -44,11 +44,11 @@ see https://en.opensuse.org/openSUSE:Build_Service_Tutorial * Use CI services --> - + First Steps - + Concepts @@ -60,12 +60,12 @@ - + Usage - + - + @@ -79,7 +79,7 @@ - + Best Practices @@ -92,7 +92,7 @@ - + Reference @@ -108,7 +108,6 @@ - diff --git a/xml/common_intro_available_doc_i.xml b/xml/common_intro_available_doc_i.xml index 86c0324b..53380b1c 100644 --- a/xml/common_intro_available_doc_i.xml +++ b/xml/common_intro_available_doc_i.xml @@ -13,7 +13,7 @@ The following documentation is available for &obsa;: - + This guide offers information about the initial setup and maintenance @@ -22,7 +22,7 @@ - + This guide is intended for users of &obs;. The first part describes basic diff --git a/xml/entity-decl.ent b/xml/entity-decl.ent index 226c1a0b..2a287be5 100644 --- a/xml/entity-decl.ent +++ b/xml/entity-decl.ent @@ -65,10 +65,10 @@ - - - - + + + + diff --git a/xml/factory.xml b/xml/factory.xml index 3d660cf9..7981e542 100644 --- a/xml/factory.xml +++ b/xml/factory.xml @@ -6,12 +6,12 @@ + xml:id="cha-obs-factory" os="opensuse"> openSUSE Factory This chapter describes how the development of the future openSUSE distribution is done within OBS. - + openSUSE:Factory project The main project is openSUSE:Factory. This project is controlled by a small group which does review all submissions according to the policies. @@ -20,7 +20,7 @@ TBD - + Devel Projects The goal of openSUSE:Factory is to always have a working state. This is needed to allow all developer groups to use it as a base for testing diff --git a/xml/obs_admin_appliance.xml b/xml/obs_admin_appliance.xml index bbcc7d90..f786db3c 100644 --- a/xml/obs_admin_appliance.xml +++ b/xml/obs_admin_appliance.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -28,7 +28,7 @@ Image Types There are different types of &obsa; appliance images. + xml:id="cha-obs-best-practices-appliance-types"> Appliance Types diff --git a/xml/obs_admin_backend.xml b/xml/obs_admin_backend.xml index a65c8b37..5b4cccf4 100644 --- a/xml/obs_admin_backend.xml +++ b/xml/obs_admin_backend.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -19,7 +19,7 @@ >man page. For example, to restart the repository server, use: systemctl restart obsrepserver.service -
+
Service Names diff --git a/xml/obs_admin_components.xml b/xml/obs_admin_components.xml index 1d6fe1de..ed7ab0dd 100644 --- a/xml/obs_admin_components.xml +++ b/xml/obs_admin_components.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_frontend.xml b/xml/obs_admin_frontend.xml index 6bf38d58..c785274f 100644 --- a/xml/obs_admin_frontend.xml +++ b/xml/obs_admin_frontend.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_integration.xml b/xml/obs_admin_integration.xml index c45c1706..76055427 100644 --- a/xml/obs_admin_integration.xml +++ b/xml/obs_admin_integration.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_tools.xml b/xml/obs_admin_tools.xml index 72ee5d40..7be29b56 100644 --- a/xml/obs_admin_tools.xml +++ b/xml/obs_admin_tools.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_ag_administration.xml b/xml/obs_ag_administration.xml index 50d5053b..5319bc3d 100644 --- a/xml/obs_ag_administration.xml +++ b/xml/obs_ag_administration.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-administration"> Administration @@ -18,19 +18,19 @@ - + Backup &obs; configuration and content needs usually a backup. The following explains suggested strategies and places considered for a backup. - + Places to consider The following is pointing to the places with admin configurations or user content. The default location places are considered here. - + Frontend Configuration @@ -43,41 +43,41 @@ The configuration is not changing usually. It is enough to backup it after config changes. - + Frontend Database The MySQL/MariaDB database backup can be done in different ways. Please consider the database manual for details. One possible way is to create dumps via mysqldump tool. The backup should be done at the same point of time as the source server. Inconsistencies can be resolved using the check_consistency tool. - + Backend Configuration The backend has a single configuration file which may got altered. This is by default /usr/lib/obs/server/BSConfig.pm . The file is not supposed to be changed usually and it can only be done by the system root user. A backup after a change is sufficient. - + Backend Content All backend content is below /srv/obs directory. This include the sources, build results and also all configuration changes done by the OBS admin users. - + Backup strategies A backup is ideally taken only from a not running service. In real live this is usually not possible, so it is important to run a backup on a production system. - + Database MySQL backup either directly from a non-primary node in the galera cluster (table dump locks the database during operation) or from a mysql slave attached to the cluster. - + Sources The sources are supposed to be backup at the same time as the database. This can get achieved by either having a dedicated instance for the source server @@ -92,7 +92,7 @@ - + Build Results Full backups via snapshots, either offered by the SAN storage or via LVM snapshot methods. Consistency is normally on repository level. Any inconsistency @@ -103,13 +103,13 @@ - + Restore A restored system might contain inconsistencies if it was taken from a running service. These can be resolved as follows. - + Check and repair database inconsistencies If either database portions or sources got restored there are chances for inconsistencies. These can be found via @@ -128,7 +128,7 @@ &prompt.user;cd /srv/www/obs/api/ &prompt.user;./bin/rake fix_project project="YOUR_PROJECT" - + Binaries All build results are evaluated by the scheduler. Therefore any inconsistency can be detected by the scheduler. One way is to enforce a cold start, which means that the @@ -151,7 +151,7 @@ - + Repair Data Corruption On-disk data might be corrupted independent of a restore. For example due to power outage, filesystem diff --git a/xml/obs_ag_build_targets.xml b/xml/obs_ag_build_targets.xml index dd9d71dd..c85a170b 100644 --- a/xml/obs_ag_build_targets.xml +++ b/xml/obs_ag_build_targets.xml @@ -3,12 +3,12 @@ %entities; ]> - Managing Build Targets - + Interconnect Using another Open Build Service as source for build targets is the easiest way to start. The advantage is, that you save local resources and @@ -26,7 +26,7 @@ create a remote project using the osc meta prj command. A remote project differs from a local project as it has a remoteurl tag (see ). + linkend="meta-data-project-meta-data"/>). Example: <project name="openSUSE.org"> <title>openSUSE.org Project Link</title> @@ -38,7 +38,7 @@ This project refers to projects hosted on the &osbs; Sending this via osc to the server: osc meta prj -m "add openSUSE.org remote" -F /tmp/openSUSE.org.prj - + Importing Distributions FIXME: describe how to do it using DoD diff --git a/xml/obs_ag_dispatch_priority.xml b/xml/obs_ag_dispatch_priority.xml index d6c09abb..bbb5c01b 100644 --- a/xml/obs_ag_dispatch_priority.xml +++ b/xml/obs_ag_dispatch_priority.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -20,9 +20,9 @@ >/build/_dispatchpriosAPI call or via the dispatch_adjust array in the - BSConfig.pm configuration + BSConfig.pm configuration file. - + The <literal>/build/_dispatchprios</literal> API Call The /build/_dispatchprios API call allows an Admin to set a priority for defined projects and repositories using the HTTP @@ -224,7 +224,7 @@
- + <literal>dispatch_adjust</literal> Array With the dispatch_adjust array in the diff --git a/xml/obs_ag_high_level_overview.xml b/xml/obs_ag_high_level_overview.xml index 9929ca07..0c017971 100644 --- a/xml/obs_ag_high_level_overview.xml +++ b/xml/obs_ag_high_level_overview.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_ag_installation_and_configuration.xml b/xml/obs_ag_installation_and_configuration.xml index 71759c0b..f54b0fc9 100644 --- a/xml/obs_ag_installation_and_configuration.xml +++ b/xml/obs_ag_installation_and_configuration.xml @@ -6,11 +6,11 @@ + xml:id="obs-cha-installation-and-configuration"> Installation and Configuration - + Planning For testing your own OBS instance, or for small setups, such as if you only want to package a few scripts into RPMS and create @@ -30,7 +30,7 @@ on one host, if it has sufficient resources. For flexibility and if you want some kind of high availability it is recommended to use virtualization for the different components. - + Resource Planning Normally, for an small or middle-sized installation, a setup with everything on one host (except workers) is sufficient. You should have a separate /srv @@ -74,7 +74,7 @@ worker hosts is more important than the other parts. - + Simple Installation In this document, we call "simple installation" an OBS installation where all OBS services are running on the same machine. @@ -86,7 +86,7 @@ Before you start the installation of the OBS, you should make sure that your hosts have the correct fully qualified hostname, and that DNS is working and can resolve all names. - + Back-end Installation The back-end hosts all sources and built packages. It also schedules the jobs. To install it, install the "obs-server" package. After installation, @@ -95,7 +95,7 @@ the defaults should be good enough for simple cases. - Read more about configuring the backend in . + Read more about configuring the backend in . The back-end consists of a number of systemd units (services): @@ -301,7 +301,7 @@ systemctl start obsrepserver.service outside. If the system is connected to an untrusted network, either block the ports with a firewall or do not run the commands at all. - + Cloud Upload Setup In order to setup the Cloud Upload feature you will need to configure the tools required per each cloud provider. Right now we only support the AWS Amazon Cloud () and Microsoft Azure @@ -341,9 +341,9 @@ our $clouduploadserver = "http://$hostname:5452"; Having an incorrect system time will cause cloud uploads to fail. - + AWS Amazon Cloud - + Authentication Workflow We are going to use the role based authentication provided by Amazon to enable the OBS instance to upload images to other user's accounts. @@ -358,7 +358,7 @@ our $clouduploadserver = "http://$hostname:5452"; The whole workflow is described in the AWS documentation. - + Credentials Setup For uploading images to AWS, OBS is using the AWS CLI tool. @@ -369,9 +369,9 @@ our $clouduploadserver = "http://$hostname:5452"; - + Microsoft Azure - + Authentication Workflow The authentication is done via Microsoft's Active Directory. The user has to create a new application and needs to @@ -391,7 +391,7 @@ our $clouduploadserver = "http://$hostname:5452"; OBS communicates with the REST API of Microsoft Azure to authenticate and upload images. - + Configuration The Application ID and the Application Key will be stored encrypted in @@ -407,7 +407,7 @@ openssl genrsa -out secret.pem openssl rsa -in secret.pem -out _pubkey -outform PEM -pubout - + Credentials setup It's important that the public key is named _pubkey and the secret key is named @@ -417,11 +417,11 @@ openssl rsa -in secret.pem -out _pubkey -outform PEM -pubout - + Front-end Installation You need to install the "obs-api" package for this and a MySQL server. - + MySQL Setup Make sure that the mysql server is started on every system reboot (use "insserv mysql" for permanent start). You should run @@ -469,7 +469,7 @@ sudo RAILS_ENV="production" rake writeconfiguration sudo chown -R wwwrun.www log tmp Now you are done with the database setup. - + Apache Setup Now we need to configure the Web server. By default, you can reach the familiar web user interface and also api both on port 443 speaking @@ -511,7 +511,7 @@ cat /srv/obs/certs/server.key /srv/obs/certs/server.crt \ cp /srv/obs/certs/server.pem /etc/ssl/certs/ c_rehash /etc/ssl/certs/ - + API Configuration Check and edit /srv/www/obs/api/config/options.yml @@ -519,9 +519,9 @@ c_rehash /etc/ssl/certs/ If you change the hostnames/ips of the API, you need to adjust frontend_host accordingly. If you want to use LDAP, you need to change the LDAP settings - as well. Look at the for + as well. Look at the for details. You will find examples and more details in the . + linkend="configuration-files"/>. It is strongly recommended to enable use_xforward: true as well here, to tell Rails to forward requests to the back-end for @@ -541,7 +541,7 @@ systemctl start memcached.service online configuration steps. - + Online Configuration To customize the OBS instance you may need to configure some settings via the OBS API and Web user interface. @@ -624,7 +624,7 @@ cat /tmp/obs.config If you want to use an interconnect to another OBS instance to reuse the build targets you can do this as Admin via the Web UI or create a project with a remoteurl tag (see ) + linkend="meta-data-project-meta-data"/>) <project name="openSUSE.org"> <title>openSUSE.org Project</title> <description> @@ -641,7 +641,7 @@ openSUSE:12.3 project as specified on the opensuse.org Build Service. this: osc -c ~/.obsadmin_osc.rc meta prj openSUSE.org -F /tmp/openSUSE.org.meta You also can import binary distribution, see for this. + linkend="managing-build-targets-importing-distributions"/> for this. The OBS has a list of available distributions used for build. This list is displayed to user, if they are adding repositories to their projects. This list can be managed via the API path /distributions @@ -664,7 +664,7 @@ openSUSE:12.3 project as specified on the opensuse.org Build Service. osc -c ~/.obsadmin_osc.rc api /distributions -T /tmp/distributions.xml - + Worker Farm To not burden your OBS back-end daemons with the unpredictable load package builds can produce (think someone builds a monstrous package like @@ -685,12 +685,12 @@ openSUSE:12.3 project as specified on the opensuse.org Build Service. OBS_SRC_SERVER, OBS_REPO_SERVERS and OBS_WORKER_INSTANCES need to be set. More details in the . + linkend="configuration-files"/>. start the worker: systemctl enable obsworker systemctl start obsworker - + Distributed Setup All OBS back-end daemons can also be started on individual machines in your network. Also, the front-end Web server and the MySQL server can run on @@ -825,15 +825,15 @@ systemctl start obswarden.service role="strong">OBS_REPO_SERVERS variable. You can also define workers with a subset of the repo servers to prioritize partitions. - + Monitoring In this chapter you will find some general monitoring instructions for the Open Build Service. All examples are based on Nagios plugins, but the information provided should be easily adaptable for other monitoring solutions. - + Endpoint Checks - + HTTP Checks: Checking Whether the HTTP Server Responds This check will output a critical if the HTTP server with ip address 172.19.19.19 (-I 172.19.19.19) listening on port 80 (-p 80) does not @@ -871,11 +871,11 @@ systemctl start obswarden.service - + Common Checks This is a list of common checks that should be run on each individual server. - + Disk Space: Checking Available Disk Space This check will output a warning if less than 10 percent disk space is available (-w 10) and output a critical if less than 5 percent disk @@ -883,7 +883,7 @@ systemctl start obswarden.service systems with type none (-x none). check_disk -w 10 -c 5 -x none - + Memory Usage: Checking Available Memory This check will output a warning if less than 10 percent memory is available (-w 10) and output a critical if less than 5 percent memory is @@ -894,7 +894,7 @@ systemctl start obswarden.service >https://exchange.nagios.org/. check_mem.pl -f -C -w 10 -c 5 - + NTP: Checking Date and Time This check will compare the local time with the time provided by the NTP server pool.ntp.org (-H pool.ntp.org). It will output a warning if the @@ -902,7 +902,7 @@ systemctl start obswarden.service differs by 1 seconds (-c 1). check_ntp_time -H pool.ntp.org -w 0.5 -c 1 - + Ping: Checking That the Server Is Alive This plugin checks if the server responds to a ping request and it will output a warning if the respond time exceeds 200ms or 30 percent @@ -910,7 +910,7 @@ systemctl start obswarden.service exceeds 500ms or 60 percent package loss. check_icmp -H server -w 200.0,30% -c 500.0,60% - + Load: Checking the Load on the Server This check will output a warning if the load value exceeded 7.0 in the last minute, 6.0 in the last 5 minutes or 5.0 in the last 15 minutes @@ -919,7 +919,7 @@ systemctl start obswarden.service minutes (-c 12.0,8.0,6.0). check_load -w 7.0,6.0,5.0 -c 12.0,8.0,6.0 - + Disk Health: Checking the Health of Local Hard Disks This check is only relevant on physical systems with local storage attached to it. It will check the disk status utilizing the S.M.A.R.T @@ -930,9 +930,9 @@ systemctl start obswarden.service check_smartmon --drive /dev/sda --drive /dev/sdb - + Other Checks - + MySQL: Checking That the MySQL Database Is Responding This check will check that the MySQL database server is running and that the database api_production is available. @@ -947,7 +947,7 @@ systemctl start obswarden.service - + Backup Status: Checking That a Valid Backup Is Available It is always advisable to check that the last backup run was successful and a recent backup is available. The check itself depends on diff --git a/xml/obs_ag_k8s_worker.xml b/xml/obs_ag_k8s_worker.xml index b68aff12..c4134b7b 100644 --- a/xml/obs_ag_k8s_worker.xml +++ b/xml/obs_ag_k8s_worker.xml @@ -1,7 +1,7 @@ - + Worker in Kubernetes Alpha Implementation @@ -16,7 +16,7 @@ So, /dev/kvm can be made available to containers via Kubernetes using device plugin API (). One of the implementations of K8s devices plugin for KVM is available here : - + Use the following manifest to deploy the KVM device plugin in a container. This plugin is packaged as k8s-device-plugin-kvm and corresponding container built here: @@ -58,13 +58,13 @@ spec: path: /var/lib/kubelet/device-plugins - + Build container image of the build service locally and load it to all worker nodes. There is sample project file here: docker load < "/path/to/docker.archive.tar.gz" - + Use the following manifest to deploy the build service worker. Here ports are hard-coded to allow easy integration with local kubelet without requiring a separate ingress-controller @@ -139,7 +139,7 @@ spec: nodePort: 32516 - + Save the following into a file launchworker.sh. Later use this file to launch the worker. Make sure you uncomment the OBS_REPO_SERVERS line and change the IP address to your build servers address cat << EOH > /etc/buildhost.config @@ -159,7 +159,7 @@ EOH obsworker restart - + Use the following command to launch the build service worker. cat launchworker.sh | kubectl exec -i -t test-worker-pod bash diff --git a/xml/obs_ag_message_bus.xml b/xml/obs_ag_message_bus.xml index 291aa543..2ca82151 100644 --- a/xml/obs_ag_message_bus.xml +++ b/xml/obs_ag_message_bus.xml @@ -6,13 +6,13 @@ + xml:id="message-bus"> Message Bus for Event Notifications The OBS has an integrated notification subsystem for sending events that are happening in our app through a message bus. We have chosen RabbitMQ as our message bus server technology based on the AMQP protocol. - + RabbitMQ RabbitMQ claims to be "the most popular open source message broker". Meaning that it can deliver asynchronous messages in many @@ -22,7 +22,7 @@ RabbitMQ is lightweight and easy to deploy on premises and in the cloud. It supports multiple messaging protocols too. And can be deployed in distributed and federated configurations to meet high-scale, high-availability requirements. - + Configuration Currently the RabbitMQ configuration is in the file options.yml. diff --git a/xml/obs_ag_overview_filesystem.xml b/xml/obs_ag_overview_filesystem.xml index adb91030..3cbf6f79 100644 --- a/xml/obs_ag_overview_filesystem.xml +++ b/xml/obs_ag_overview_filesystem.xml @@ -6,15 +6,15 @@ + xml:id="obs-cha-overview-filesystem"> File System Overview - + Configuration Files - + Front-end Configuration - The front-end is configured with 4 files: + The front-end is configured with four files: /srv/www/obs/api/config/database.yml @@ -29,7 +29,7 @@ /etc/apache2/vhosts.d/obs.conf - + <filename>database.yml</filename> This file has the information needed to access the database. It contain credentials for the database access and should be only readable by @@ -174,7 +174,7 @@ - + <filename>options.yml</filename> The configuration file /srv/www/obs/api/config/options.yml is the default configuration file for the Open Build Service Web UI and API. It @@ -637,7 +637,7 @@ development: memcached_host: cache - + <filename>feature.yml</filename> The configuration file /srv/www/obs/api/config/feature.yml contains the default configuration about features that can be enabled or @@ -727,7 +727,7 @@ test: ]]> - + Apache Virtual Host <filename>obs.conf</filename> The Apache configuration depends on the Apache version and which extra options are used, so use the documentation of the Apache version you @@ -837,7 +837,7 @@ LimitRequestFieldsize 20000 </VirtualHost> - + Back-end Configuration The Back-end is configured with 2 files: @@ -850,7 +850,7 @@ LimitRequestFieldsize 20000 global variables - + <filename>/etc/sysconfig/obs-server</filename> This script is used to set up the basic paths and the worker. the most important settings are the - + BSConfig.pm This file is a perl module used by most back-end scripts, it mainly defines global variables. Since it is a perl module, after changes @@ -2467,7 +2467,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2482,7 +2482,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2497,7 +2497,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2512,7 +2512,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2527,7 +2527,7 @@ OBS_WORKER_SCRIPT_URL="" 0 1 - see + see @@ -2542,7 +2542,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2557,7 +2557,7 @@ OBS_WORKER_SCRIPT_URL="" 0 1 - see + see @@ -2572,7 +2572,7 @@ OBS_WORKER_SCRIPT_URL="" - see + see @@ -2798,9 +2798,9 @@ if (-r $hostconfig) { - + Log Files - + Front-end The front-end log files are found under /srv/www/obs/api/log. @@ -2832,7 +2832,7 @@ if (-r $hostconfig) { - + Back-end The back-end log files are found by default under /srv/obs/log/. @@ -2884,7 +2884,7 @@ if (-r $hostconfig) { - + <filename>/srv/obs</filename> Tree The default back-end data directory is located under /srv/obs/. Here are a bunch of subdirectories used for @@ -2894,7 +2894,7 @@ if (-r $hostconfig) { which stores the global OBS configuration for the back-end. You should not modify this file directly, but use the API /configuration interface instead, since this information needs to kept in sync with the front-end. - + <filename>build</filename> Directory In this subdirectory managed by the repo server daemon, all repository data, metadata and build results are stored in a hierarchical @@ -2928,29 +2928,29 @@ if (-r $hostconfig) { │ ├── srtp │ └── wget - + <filename>cloudupload</filename> Directory Info for cloud upload jobs is stored here, it has a subdir named done for storing the already finished jobs. - + <filename>db</filename> Directory Back-end database root directory use by the source server, repo server scheduler and publisher. Nobody should touch this. - + <filename>diffcache</filename> Directory Cache for source server compare operations. - + <filename>events</filename> Directory Communication between services. - + <filename>info</filename> Directory Scheduler information managed by the scheduler and used by the repo server. - + <filename>jobs</filename> Directory The build jobs are stored in the /srv/obs/jobs directory. They are organized bybuild architecture: @@ -2963,34 +2963,34 @@ if (-r $hostconfig) { The jobs/load file contains statistical data about the build jobs. - + <filename>log</filename> Directory Contains the log files of the back-end daemons. - + <filename>projects</filename> Directory Contains the project hierarchy and metadata under revision control. - + <filename>remotecache</filename> Directory Cache for remote repository information. - + <filename>repos</filename> Directory Directory managed by the publisher to collect build results, also used by the repo server and scheduler to find build results. - + <filename>repos_sync</filename> Directory Directory with files pointing to the project root directories, helper for publisher rsync. - + <filename>run</filename> Directory State and lock information for the back-end daemons - + <filename>sources</filename> Directory All package sources under revision control in one directory per package, managed by the source server. Package sources are by default @@ -3011,24 +3011,24 @@ if (-r $hostconfig) { ├── :service └── :upload - + <filename>trees</filename> Directory Revision control data for project and packages, managed by the source server. - + <filename>upload</filename> Directory Temporary directory for uploading files for other back-end components. - + <filename>workers</filename> Directory Worker information - + Metadata - + &obsa; Revision Control This section gives a short generic overview how the revision information are stored in the OBS back-end for packages and projects. The @@ -3038,7 +3038,7 @@ if (-r $hostconfig) { /srv/obs/sources directories. The revision information is stored in separate files by the Source Server in the /srv/obs/projects directory. - + OBS revision control files The revision information is stored in simple CSV like file format with a bar (|) as delimiter between the 8 columns. The files do have the @@ -3198,7 +3198,7 @@ if (-r $hostconfig) { 0a17daaa913df9e50ee65e83a1898363 package1.spec 1f810b3521242a98333b7bbf6b2b7ef7 test1.sh - + &obsa; Revision API The revision info can be retrieved via API calls for the specific package, for example, using @@ -3210,7 +3210,7 @@ if (-r $hostconfig) { "comment=some+comment" can be used to set a commit message. - + Project Metadata Project metadata are XML files containing the meta project information, such as title, description, related user and groups with @@ -3445,7 +3445,7 @@ if (-r $hostconfig) { </repository> </project> - + Package Metadata XML file about package meta information, like Title, description, related user and groups with roles, build settings, publish settings, debug @@ -3468,7 +3468,7 @@ if (-r $hostconfig) { </debuginfo> </package> - + Attribute Metadata Attributes can be used to add special information to packages. Attributes can be used to trigger special actions. @@ -3483,7 +3483,7 @@ if (-r $hostconfig) { </attribute> </attributes> - + Job Files Jobs are stored by the scheduler in the /srv/obs/jobs directory and contain the build setup diff --git a/xml/obs_ag_publish_hooks.xml b/xml/obs_ag_publish_hooks.xml index 2e885001..b0bc558b 100644 --- a/xml/obs_ag_publish_hooks.xml +++ b/xml/obs_ag_publish_hooks.xml @@ -6,7 +6,7 @@ + xml:id="publisher-hooks"> Publisher Hooks The job of the publisher service is to publish the built packages and/or images by creating repositories that are made available through a web @@ -15,7 +15,7 @@ to different servers or do anything with them that comes to mind. These scripts are called publisher hooks. - + Configuring Publisher Hooks Hooks are configured via the configuration file /usr/lib/obs/server/BSConfig.pm, where one script per @@ -99,9 +99,9 @@ our $publishedhook = { script. The scripts are called without a timeout. - + Example Publisher Scripts - + Simple Publisher Hook The following example script ignores the packages that have changed and copies all RPMs from the repository directory to a target @@ -120,7 +120,7 @@ rsync -a --log-file=$LOGFILE --mkpath $PATH_TO_REPO/ $DST_REPO_DIR/$PRJ_PATH/$ sudo -u obsrun /usr/local/bin/publish-hook.sh Product/SLES11-SP1 \ /srv/obs/repos/Product/SLE11-SP1 - + Advanced Publisher Hook The following example script reads the destination path from a parameter that is configured with the hook script: diff --git a/xml/obs_ag_security_concepts.xml b/xml/obs_ag_security_concepts.xml index 71c000b8..77f40876 100644 --- a/xml/obs_ag_security_concepts.xml +++ b/xml/obs_ag_security_concepts.xml @@ -6,11 +6,11 @@ + xml:id="obs-cha-security-concepts"> Security Concepts - + General Paradigm The general paradigm of &obs; is to host all content on its own. Every part required to rebuild a package is hosted in &obs; to guarantee reproducibility. @@ -18,11 +18,11 @@ However, optional services to integrate remote resources exist as well. These resources are either mirrored and stored in revision control system or just cached. - + Frontend The API and web interface frontends is the only part which must be accessible from public network. A SSL/TLS certificate is highly recommended. - + Access to Mirror Servers The following services require access to stage servers. These servers can be used to publish content without the need to make &obs; server parts @@ -40,7 +40,7 @@ - + Access to the Public Network The following services may require access to the public network. @@ -67,14 +67,14 @@ - + Worker network It is recommended to run the &obs; workers in an isolated network. This is an additional security mechanism in case of a security breach on a worker. This network needs access to the source and repository servers of the &obs; backend, but nowhere else. - + Signer network It is recommended to run the signd on an isolated host. The signer services need to stay on the &obs; backend servers, they are just used for scheduling @@ -88,7 +88,7 @@ backend server components (source server and publisher). - + Build Environment The build environment is created by obsworker instances via the build script. Inside the build instances unverified and potentially harmful code is executed. @@ -112,7 +112,7 @@ source packages are rebuildable without root permissions. - + Source Revision System The source revision storage system is part of &obs;. The identification of sources still happens using MD5 sums for historic reasons. MD5 is considered to be still @@ -126,7 +126,7 @@ builds, but it should be avoided for base projects. - + Permission Handling Authorization for write operations is done via the maintainer role on package or project level. On project level the projects are organized in namespaces @@ -136,7 +136,7 @@ top level namespaces (for example, openSUSE: namespace in our reference instance). - + Signature Handling Signatures are used to proof the origin of a shipment independent of &obs; instance. Once the signd daemon has @@ -181,17 +181,17 @@ - + Trust Zones &OBS; components deal with different trust zones. These are separated via network or virtualization mechanics. - + Public Zones Public zones are areas where any code under user control is running. - + External Network This can be the public Internet if the &obs; instance is a public @@ -201,7 +201,7 @@ connections to the Internet as described below. - + Untrusted Code All code which is used to build content is considered @@ -215,12 +215,12 @@ - + Demilitarized Zone (DMZ) The Demilitarized Zone contains services which interact with the public zone directly. - + &obs; Frontend The frontend service is the only service which provides an open port. @@ -230,7 +230,7 @@ the source server only. - + &obs; Frontend Background Services &obs; frontend background services handle less time critical operations. @@ -238,7 +238,7 @@ trackers, sending notifications or long running jobs. - + Stage Server The stage server is providing the public content of the &obs; backends. @@ -246,7 +246,7 @@ a mirror infrastructure. - + Cloud Uploader The cloud uploader is uploading build results on user request. It reads @@ -255,7 +255,7 @@ This is an optional service. - + Source Service Server The source service server is acting based on uploaded sources. The @@ -266,12 +266,12 @@ - + Internal Zone The internal zone is running service which are supposed to work without further external dependency. - + &obs; Source Server The source server coordinates changes to package and project configuration. @@ -281,7 +281,7 @@ There can only be a single source server per OBS install. - + &obs; Binary Servers Binary Servers are hosting all content of build results. They @@ -289,7 +289,7 @@ staging server. - + External Dependencies The internal zone has no external dependency. @@ -300,19 +300,19 @@ - + Worker Zone The &obs; workers are running in an own isolated network. They access only source and binary servers from internal zone. - + Signing Server The signing server is supposed to be the most isolated service. It is supposed to be stateless after initial setup. Avoid to enable any remote access. -
+
Trust Zones of &obs; diff --git a/xml/obs_ag_source_publish.xml b/xml/obs_ag_source_publish.xml index a5a4267f..c50af687 100644 --- a/xml/obs_ag_source_publish.xml +++ b/xml/obs_ag_source_publish.xml @@ -6,7 +6,7 @@ + xml:id="source-publish"> Source Publisher The job of the source publish service is to publish all sources for directly before published binaries. This will include the sources of repackaged @@ -14,7 +14,7 @@ binaries. For example, the sources of RPMs which are used inside of product, appliance or container images. A prerequisite for this is that OBS has enabled content tracking for the used projects. - + Configuring Source Publisher The source publishing can be configured via the file /usr/lib/obs/server/BSConfig.pm, where it can be @@ -26,7 +26,7 @@ content tracking for the used projects. our $sourcepublish_filter = [ "openSUSE:.*", "SUSE:.*" ]; - + Considerations The source publishing service is publishing the sources as they are hosted in &obs;. This means these are the unprocessed sources and the content is not identical to the @@ -35,7 +35,7 @@ content tracking for the used projects. As a consequence hints like NoSource: tags in spec files are ignored. The only way to disable publishing for the user is to disable access or sourceaccess via the flags. - The filesystem structure is $project/$package/$srcmd5/. A + The filesystem structure is $project/$package/$srcmd5/. A inside of binary builds can be used to find the right sources. &obs; will care for de-duplication on the rsync server. This must get implemented there. diff --git a/xml/obs_ag_source_service.xml b/xml/obs_ag_source_service.xml index f5be344c..1510beae 100644 --- a/xml/obs_ag_source_service.xml +++ b/xml/obs_ag_source_service.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_ag_spider_identification.xml b/xml/obs_ag_spider_identification.xml index efdc09d0..c04c10b8 100644 --- a/xml/obs_ag_spider_identification.xml +++ b/xml/obs_ag_spider_identification.xml @@ -6,7 +6,7 @@ + xml:id="obs-spider-identification"> Spider Identification OBS is hiding specific parts/pages of the application from search crawlers (DuckDuckGo, Google, etc.), mostly for performance reasons. Which diff --git a/xml/obs_ag_tools.xml b/xml/obs_ag_tools.xml index 48a11a31..d6e7d625 100644 --- a/xml/obs_ag_tools.xml +++ b/xml/obs_ag_tools.xml @@ -3,9 +3,9 @@ %entities; ]> - + Tools - + <command>obs_admin</command> obs_admin is a command-line tool used on the back-end server(s) to manage running services, submit maintenance tasks, and debug problems. @@ -142,7 +142,7 @@ Note: the --update-*-db calls are usually only needed when corrupt data has been --show-delta-store <file> Show delta store statistics - + &osccmd; The osc command-line client is mainly used by developers and packagers. But for some tasks, admin people also need this tool. It too has builtin help: @@ -158,7 +158,7 @@ osc -A https://api.testobs.org give this file restrictive access rights, only read/write access for your user should be allowed. osc allows to store the password in other ways (in keyrings for example) and may use different methods for authentication like -Kerberos see +Kerberos see For admins the most important osc subcommands are: @@ -174,12 +174,12 @@ API - to read and write online configuration data - + <command>osc meta</command> Subcommand The osc meta subcommand is documented inside the "osc" tool itself. This documentation can be displayed by issuing the command: osc meta --help - + <command>osc api</command> Subcommand The osc api subcommand is documented inside the "osc" tool itself. This documentation can be displayed by issuing the command: osc api --help diff --git a/xml/obs_ag_troubleshooting.xml b/xml/obs_ag_troubleshooting.xml index 834d61f8..c954b2de 100644 --- a/xml/obs_ag_troubleshooting.xml +++ b/xml/obs_ag_troubleshooting.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-troubleshooting"> Troubleshooting @@ -25,16 +25,16 @@ description and so on. Most of them should not happen if the packager does test the build locally before committing it to the OBS. This type of problems is not covered by this chapter. - + General Hints - If you detect unexpected behavior of the open build service, you + If you detect unexpected behavior of the OBS, you should follow some rules to locate the problem: Consult the log files, for the back-end look at /srv/obs/log for the back-end log files and /srv/www/obs/api/log for the front-end log files. - See the Log files for more details. + See the Log files for more details. @@ -64,7 +64,7 @@ - + Debugging Front-end Problems If you get unexpected results from submitting commands with the osc tool, you can diff --git a/xml/obs_ag_unpublish_hooks.xml b/xml/obs_ag_unpublish_hooks.xml index 31f7cddf..18e9a80d 100644 --- a/xml/obs_ag_unpublish_hooks.xml +++ b/xml/obs_ag_unpublish_hooks.xml @@ -6,7 +6,7 @@ + xml:id="unpublisher-hooks"> Unpublisher Hooks The job of the publisher service is to publish the built packages and/or images by creating repositories that are made available through a web @@ -16,7 +16,7 @@ called unpublisher hooks. Unpublisher hooks are run before the publisher hooks. - + Configuring Unpublisher Hooks Hooks are configured via the configuration file /usr/lib/obs/server/BSConfig.pm, where one script per @@ -107,9 +107,9 @@ our $unpublishedhook = { hook. - + Example Unpublisher Scripts - + Simple Unpublisher Hook The following example script deletes all packages from the target directory that have been removed from the repository. @@ -137,7 +137,7 @@ done x86_64/icinga-1.13.3-1.3.x86_64.rpm \ x86_64/icinga-devel-1.13.3-1.3.x86_64.rpm - + Advanced Unpublisher Hook The following example script reads the destination path from a parameter that is configured via the hook script: diff --git a/xml/obs_ag_user_management.xml b/xml/obs_ag_user_management.xml index 9c09b5be..4415e554 100644 --- a/xml/obs_ag_user_management.xml +++ b/xml/obs_ag_user_management.xml @@ -6,7 +6,7 @@ + xml:id="user-and-group-management"> Managing Users and Groups The OBS has an integrated user and group management with a role based access rights model. In every OBS instance, at least one user need to exist @@ -14,7 +14,7 @@ and instead of adding a list of users to a project/package role user can be added to a group and the group will be added to a project or package role. - + User and Group Roles The OBS role model has one global role: Admin, which can be granted to users. An OBS admin has access to all projects and packages via the API @@ -96,7 +96,7 @@ - + Standalone User and Group Database OBS provides its own user database which can also store a password. The authentication to the API happens via HTTP BASIC AUTH. See the API @@ -107,7 +107,7 @@ confirmation is needed after registration before the user may login. - + Users and Group Maintainers Administrators can create groups, add users to them, remove users from them and @@ -116,7 +116,7 @@ osc api -d "<group><title><group-title></title><email><group-email></email><maintainer userid="<user-name>"/><person><person userid="<user_name>"/></person></group>' -X PUT "/group/<group-title>" - + Gravatar for Groups In certain cases, it might be desirable to show a Gravatar for a group, similar to the users. In order to show a Gravatar, an email address is needed. @@ -125,7 +125,7 @@ osc api -X POST "/group/<group-title>?cmd=set_email&email=<groups-email-address>" - + Proxy Mode The proxy mode can be used for specially secured instances, where the OBS web server shall not get connected to the network directly. There @@ -144,7 +144,7 @@ With the proxy mode the user still need to be registered in the OBS and all OBS roles and user properties are managed inside the OBS. - + &obsa; Proxy Mode Configuration Currently the LDAP configuration is in the options.yml file. @@ -184,7 +184,7 @@ - + LDAP/Active Directory The LDAP support was considered experimental and not officially @@ -231,7 +231,7 @@ member attributes of the group are parsed and all current users which are in the local database become members. - + OBS LDAP Configuration Currently the main OBS LDAP configuration is in the @@ -741,9 +741,9 @@ ldap_group_objectclass_attr: group ldap_obs_admin_group: obsadmins - + Authentication Methods - + LDAP Methods The LDAP mode has 2 methods to check authorization: @@ -764,7 +764,7 @@ ldap_obs_admin_group: obsadmins will not be available until you are bind with a privilege user. - + Kerberos In OBS you can use single sign on via Kerberos tickets. OBS Kerberos configuration resides in the diff --git a/xml/obs_architecture.xml b/xml/obs_architecture.xml index 6e6edebe..7549e747 100644 --- a/xml/obs_architecture.xml +++ b/xml/obs_architecture.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -16,11 +16,11 @@ - + Overview Graph &OBS; is not a monolithic server; it consists of multiple daemons - that fulfill different tasks (see ). -
+ that fulfill different tasks: +
Simplified OBS Component Overview @@ -29,8 +29,7 @@
- The OBS Back-end - manages the source files and build jobs of the OBS. + The OBS Backend manages the source files and build jobs of the OBS. @@ -179,7 +178,7 @@ - + Communication Flow The communication flow can be split into the following major parts: @@ -222,7 +221,7 @@ other back-end components. -
+
OBS Communication (Simplified) @@ -234,7 +233,7 @@
- The figure shows the + The figure shows the communication flow between the &obsa; components if a package source (for example, a _service file) was updated: diff --git a/xml/obs_authorization_token.xml b/xml/obs_authorization_token.xml index 8f4140c4..0dd196de 100644 --- a/xml/obs_authorization_token.xml +++ b/xml/obs_authorization_token.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_basic_workflow.xml b/xml/obs_basic_workflow.xml index 9b19c62b..31064314 100644 --- a/xml/obs_basic_workflow.xml +++ b/xml/obs_basic_workflow.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -18,7 +18,7 @@ TBD --> - + Setting Up Your Home Project toms 2017-08-25: Suggestion by sknorr: generic section plus home project (cross refs only) @@ -27,7 +27,7 @@ This section shows how to set up your home project with the command line tool &osccmd;. For more information about setting up your home project with the Web UI, see - . + . This chapter is based on the following assumptions: @@ -41,19 +41,19 @@ - You have installed &osccmd; as described in . + You have installed &osccmd; as described in . - You have configured &osccmd; as described in . + You have configured &osccmd; as described in . Setting Up Your Home Project - + Get a list of all available build targets of your &obsa; instance: @@ -66,7 +66,7 @@ openSUSE:Tools, openSUSE:Templates. - + Configure your build targets with: @@ -102,7 +102,7 @@ Add more repository elements as needed. Insert the information - from into the + from into the project attribute. @@ -142,7 +142,7 @@ is valid, &osccmd; will save it. Otherwise, it will show an error and prompt you whether to Try again?. In this case, press n. Your changes will be lost and you will need to start - from again. + from again. @@ -151,7 +151,7 @@ - + Creating a New Package This section covers how to create packages for an arbitrary software project, @@ -159,7 +159,7 @@ assume that this project contains source code which you want to package for one or more &suse; (openSUSE) distributions. We assume the setup of your home project in your &obsa; instance is - already done. If not, refer to . + already done. If not, refer to . To create a package from the upstream project, do the following: @@ -303,7 +303,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; -->openSUSE_Tumbleweed x86_64 *.spec - If you encounter problems, see . + If you encounter problems, see . @@ -343,7 +343,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + Investigating the Local Build Process toms 2017-08-22: https://en.opensuse.org/openSUSE:Build_Service_Tutorial#Correct_Errors_in_the_Local_Build_Process @@ -353,16 +353,16 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + - + toms 2017-08-22: Troubleshooting? - + Build Log Each build produces a log file on &obsa;. This log file can be viewed by @@ -412,7 +412,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + Local Build Root Directory If you build a package locally and you get a build error, investigate @@ -444,30 +444,30 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; The build root contains the following structure: - + Directory Structure of a Build Root (<filename>/var/tmp/build-root/</filename>) /home/abuild/ └── rpmbuild - ├── BUILD - ├── BUILDROOT - ├── OTHER - ├── RPMS + ├── BUILD + ├── BUILDROOT + ├── OTHER + ├── RPMS │ ├── i386 │ ├── noarch │ └── x86_64 - ├── SOURCES - ├── SPECS - └── SRPMS + ├── SOURCES + ├── SPECS + └── SRPMS toms 2017-08-22: https://rpm-packaging-guide.github.io/#rpm-packaging-workspace - + Contains directory named after the package name. In spec files, the name of the package directory is referenced using the %buildroot macro. - + If the build process was unable to create a package, this directory contains all files and directories which are installed in the target @@ -479,12 +479,12 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; emptied. - + Usually contains the file rpmlint.log. - + If the build was successful, stores binary RPMs into subdirectories of architecture @@ -492,17 +492,17 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; x86_64). - + All source files from the working copy will be copied here. - + toms 2017-08-22: empty? - + Stores source RPMs into this directory. @@ -512,7 +512,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + Adding Dependencies to Your Project Software usually depends on other software: To run an application, you @@ -534,24 +534,24 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + - + (layering) - + (linking and aggregating) - + Adding Dependencies to Your Build Recipes toms 2017-08-24: Should probably go into the concept part? toms 2017-08-24: should we explain hard and soft requirements? @@ -561,7 +561,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; requirements). Both belong to the header of the spec file. - + Excerpt of Build and Installation Requirements Name: foo-example Version: 1.0.0 @@ -570,7 +570,7 @@ Requires: zool >= 1.5.6 toms 2017-08-24: Version compare with zypper vcmp? - + Associating Other Repositories with Your Repository There is no need to duplicate the work of others. If you need a specific @@ -597,7 +597,7 @@ Requires: zool >= 1.5.6 &prompt.user;osc meta prj --edit &obshome1; - + Search for repository elements. For example, to allow usage packages from devel:languages:python in a @@ -628,7 +628,7 @@ Requires: zool >= 1.5.6 - + Add more path elements under the same repository element. @@ -636,14 +636,14 @@ Requires: zool >= 1.5.6 - If necessary, repeat and - to add path + If necessary, repeat and + to add path elements to repository elements of other distributions or releases. - + Reusing Packages in Your Project toms 2017-08-30: This part and its subsections needs to be further discussed. "Aggregate" as a word doesn't really fit with the @@ -657,7 +657,7 @@ Requires: zool >= 1.5.6 toms 2017-08-30: add a notes when NOT to use the two methods. - + Aggregating a Package An aggregate package is a pointer to an &obsa; package. @@ -706,7 +706,7 @@ Requires: zool >= 1.5.6 contains the _aggregate file. - + Linking a Package A linked package is a clone of another package with @@ -764,7 +764,7 @@ At revision 1. - + Manage Group Users with Maintainer rights can add users to their group and remove users diff --git a/xml/obs_best_practice_advanced.xml b/xml/obs_best_practice_advanced.xml index 8d2d4d21..54915acd 100644 --- a/xml/obs_best_practice_advanced.xml +++ b/xml/obs_best_practice_advanced.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_basics.xml b/xml/obs_best_practice_basics.xml index 158a7bb9..ee13e5e3 100644 --- a/xml/obs_best_practice_basics.xml +++ b/xml/obs_best_practice_basics.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_boot_strapping.xml b/xml/obs_best_practice_boot_strapping.xml index 4346dfe1..100f9e41 100644 --- a/xml/obs_best_practice_boot_strapping.xml +++ b/xml/obs_best_practice_boot_strapping.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_distribution_setup.xml b/xml/obs_best_practice_distribution_setup.xml index 222d912a..171aa25f 100644 --- a/xml/obs_best_practice_distribution_setup.xml +++ b/xml/obs_best_practice_distribution_setup.xml @@ -3,7 +3,7 @@ %entities; ]> -Distribution Setup +Distribution Setup This document describes ways to set up an entire distribution, including @@ -12,7 +12,7 @@
General Project Setup for a Maintained Distribution - are the + are the
diff --git a/xml/obs_best_practice_howto.xml b/xml/obs_best_practice_howto.xml index f83eecef..6a9c7b83 100644 --- a/xml/obs_best_practice_howto.xml +++ b/xml/obs_best_practice_howto.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_image_templates.xml b/xml/obs_best_practice_image_templates.xml index ec49707b..d51b6ec8 100644 --- a/xml/obs_best_practice_image_templates.xml +++ b/xml/obs_best_practice_image_templates.xml @@ -4,14 +4,14 @@ %entities; ]> - Image Templates &image_template_introduction_paragraph; + xpointer="image-template-introduction-paragraph"/>--> How you can create your own image templates will be shown here.
&obsa; Templates Page @@ -71,7 +71,7 @@ &kiwi; configurations usually consists of an xml configuration root tarball. + xpointer="image-template-icon-paragraph"/>--> &image_template_icon_paragraph; For a full list of image descriptions and general information about building images with KIWI, see the - diff --git a/xml/obs_best_practice_kernel_build.xml b/xml/obs_best_practice_kernel_build.xml index 42671139..390c3f4c 100644 --- a/xml/obs_best_practice_kernel_build.xml +++ b/xml/obs_best_practice_kernel_build.xml @@ -3,7 +3,7 @@ %entities; ]> -Building Kernel Modules +Building Kernel Modules TBD: via Ann Davis? diff --git a/xml/obs_best_practice_kiwi_editor.xml b/xml/obs_best_practice_kiwi_editor.xml index 89936826..69432c81 100644 --- a/xml/obs_best_practice_kiwi_editor.xml +++ b/xml/obs_best_practice_kiwi_editor.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_local_setup.xml b/xml/obs_best_practice_local_setup.xml index 84f25de7..d5945979 100644 --- a/xml/obs_best_practice_local_setup.xml +++ b/xml/obs_best_practice_local_setup.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_maintained_release.xml b/xml/obs_best_practice_maintained_release.xml index 5933fe0c..24942c1f 100644 --- a/xml/obs_best_practice_maintained_release.xml +++ b/xml/obs_best_practice_maintained_release.xml @@ -3,7 +3,7 @@ %entities; ]> -Distribution Setup +Distribution Setup This document describes ways to set up an entire distribution, including @@ -12,7 +12,7 @@
General Project Setup for a Maintained Distribution - are the + are the
diff --git a/xml/obs_best_practice_manage_group.xml b/xml/obs_best_practice_manage_group.xml index fe18bc1c..6a2ccb25 100644 --- a/xml/obs_best_practice_manage_group.xml +++ b/xml/obs_best_practice_manage_group.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_osc_examples.xml b/xml/obs_best_practice_osc_examples.xml index c3331a3e..cb56f8cc 100644 --- a/xml/obs_best_practice_osc_examples.xml +++ b/xml/obs_best_practice_osc_examples.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_staging_workflow.xml b/xml/obs_best_practice_staging_workflow.xml index 71f1b421..79cc1fb0 100644 --- a/xml/obs_best_practice_staging_workflow.xml +++ b/xml/obs_best_practice_staging_workflow.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_upstream.xml b/xml/obs_best_practice_upstream.xml index 9ea7e15d..0ffa15c3 100644 --- a/xml/obs_best_practice_upstream.xml +++ b/xml/obs_best_practice_upstream.xml @@ -3,7 +3,7 @@ %entities; ]> - + Publishing Upstream Binaries @@ -26,7 +26,7 @@ More information about setting up your own private OBS instance can be - found in . + found in . @@ -152,10 +152,10 @@ on newer websites. An example of download page can be following one . You can see how it looks like in - . It + . It contains links to the packages and instructions how to install them. -
+
openSUSE download page for package from OBS @@ -169,9 +169,9 @@ any number of &-separated parameters. But at least two of them - project and package - are required. All parameters with descriptions can be found in - . + . - +
Parameters for Download Page diff --git a/xml/obs_best_practice_webui_usage.xml b/xml/obs_best_practice_webui_usage.xml index 69542cf9..cf205de2 100644 --- a/xml/obs_best_practice_webui_usage.xml +++ b/xml/obs_best_practice_webui_usage.xml @@ -3,7 +3,7 @@ %entities; ]> - Wonderful, we've added a pointer to the sources! Now we need to add a repository, so the builder knows the target-distribution to build packages for. How to add a repository to a project is documented at . + linkend="cha-obs-best-practices-webuiusage-add-repository"/>. Package Page, Build Log and Project Monitor Page @@ -286,13 +286,13 @@ flood Managing Repositories This section will show how you can manage your project's repositories. - + Adding a repository To add a repository to your project, click on "Add Repositories" on the project's repository tab. This will direct you to a list of possible distributions you can build packages for, see . -
+ linkend="cha-obs-best-practices-webuiusage-add-repository-screenshot"/>. +
Adding a Repository to a Project @@ -328,9 +328,8 @@ flood
The minimal set of fields you have to enter are architecture, repository type and the URL that provides the binary packages. Detailed - information about the data you can enter here you can find at the DoD concept section. Press "Save" to create the repository. + information about the data you can enter here can be found at + . Press "Save" to create the repository.
Download on Demand Repository Form diff --git a/xml/obs_binary_tracking.xml b/xml/obs_binary_tracking.xml index 669c60c9..5417bf9f 100644 --- a/xml/obs_binary_tracking.xml +++ b/xml/obs_binary_tracking.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_build_config.xml b/xml/obs_build_config.xml index e21d8eca..dccd6065 100644 --- a/xml/obs_build_config.xml +++ b/xml/obs_build_config.xml @@ -3,14 +3,14 @@ %entities; ]> - Build Configuration - + About the Build Configuration Each project has a build configuration which @@ -93,7 +93,7 @@ - + Configuration File Syntax The syntax is basically the same as in RPM spec files. @@ -128,7 +128,7 @@ The following list contains a list of allowed keywords in the build configuration (prjconf): - + Available Keywords in Build Configuration @@ -958,7 +958,7 @@ Support: pax debbuild - + Building with ccache or sccache The usage of ccache or sccache can be enabled for each package by @@ -997,7 +997,7 @@ Support: pax debbuild - + Macro Definitions in the Build Configuration You can use rpm macro definitions in the build configuration (prjconf) to improve @@ -1056,7 +1056,7 @@ Support: pax debbuild - + Macros for the Build Configuration Only To specify macros for the building process, use the %define @@ -1071,7 +1071,7 @@ Support: pax debbuild the build configuration. - + Macros Used in Spec Files Only To define the values of macros used in spec files, `%define` is %entities; ]> - @@ -57,7 +57,7 @@ - + Constraint Qualifiers In general, build constraints are specified in terms of a qualifier and a value. The qualifier expresses "what" - the build worker parameter @@ -76,7 +76,7 @@ and unit=G means "the value is expressed in units of Gigabytes. For a full treatment of constraint syntax, see - . + . Constraint scope and precedence @@ -102,7 +102,7 @@ defined in the project config by adding lines as so: Constraint: <QUALIFIER> <VALUE> The QUALIFIER syntax is the same as used in RPM spec files, documented - in . Within the project configuration, + in . Within the project configuration, individual Constraint lines can be enclosed in guards to make a constraint apply only to certain architectures or repositories. For example: @@ -118,7 +118,7 @@ Constraint: hardware:disk:size unit=M 4000 project itself, but also all projects that build against it. For a full treatment of constraint syntax, see - . + . Package-scoped constraints @@ -144,7 +144,7 @@ Constraint: hardware:disk:size unit=M 4000 </constraints> For details on constraint qualifiers and how to specify them in a _constraints file, see - . + . Build recipe-scoped constraints @@ -173,18 +173,18 @@ Constraint: hardware:disk:size unit=M 4000 pool of compliant build workers down to a very low number, or even to zero. (A low number of compliant build workers means your build may not start for a long time, and no compliant workers at all will cause the build to fail. - See for details.) + See for details.) By default, constraints applied to build workers regardless of architecture. However, you may only be interested in certain architectures - and not in others. See + and not in others. See for how to get architecture-specific information on which workers satisfy your constraints. - + Constraint syntax This section describes the various constraint qualifiers and their syntax. @@ -425,7 +425,7 @@ Constraint: hardware:cpu:flag sse2 - + Constraint Handling What happens when someone sets a constraint so high, that the OBS instance does not have even a single worker that meets it? What happens @@ -470,7 +470,7 @@ no compliant workers (constraints mismatch hint: hardware:processors sandbox) Please adapt your constraints. - + Checking Constraints with &osccmd; You can check the constraints of a project or package with the osc tool. You have to be in an &osccmd; working directory. diff --git a/xml/obs_build_containers.xml b/xml/obs_build_containers.xml index 52d95b8f..52c96b8d 100644 --- a/xml/obs_build_containers.xml +++ b/xml/obs_build_containers.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -19,7 +19,7 @@ libraries, executables and shared resource files. - + Supported Container Formats @@ -84,7 +84,7 @@ Flatpak packages can be built in the Open Build Service, see - for further details. + for further details. @@ -102,7 +102,7 @@ Mkosi allows building images for rpm, arch, deb, and gentoo based distributions, see - for further details. + for further details. @@ -117,7 +117,7 @@ --> - + Container Registry @@ -184,7 +184,7 @@ xlink:href="https://registry.opensuse.org/">registry.opensuse.org - + Container Image Signatures diff --git a/xml/obs_build_preinstall.xml b/xml/obs_build_preinstall.xml index 92755eb4..1a99629b 100644 --- a/xml/obs_build_preinstall.xml +++ b/xml/obs_build_preinstall.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_build_process.xml b/xml/obs_build_process.xml index 2068ee53..bbe538bf 100644 --- a/xml/obs_build_process.xml +++ b/xml/obs_build_process.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_concepts.xml b/xml/obs_concepts.xml index 6c81e463..647a1d59 100644 --- a/xml/obs_concepts.xml +++ b/xml/obs_concepts.xml @@ -4,7 +4,7 @@ %entities; ]> - diff --git a/xml/obs_concepts_dod.xml b/xml/obs_concepts_dod.xml index 2b900cf1..a062a597 100644 --- a/xml/obs_concepts_dod.xml +++ b/xml/obs_concepts_dod.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_concepts_scm.xml b/xml/obs_concepts_scm.xml index 79ccab78..49d9a223 100644 --- a/xml/obs_concepts_scm.xml +++ b/xml/obs_concepts_scm.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_cross_architecture_build.xml b/xml/obs_cross_architecture_build.xml index 5a13a5d9..8b780757 100644 --- a/xml/obs_cross_architecture_build.xml +++ b/xml/obs_cross_architecture_build.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_glossary.xml b/xml/obs_glossary.xml index 8b017736..6b75511b 100644 --- a/xml/obs_glossary.xml +++ b/xml/obs_glossary.xml @@ -10,21 +10,21 @@ ******* Please post on the OBS mailing list your suggestion, if you ******** ******* are unsure. ******** --> - Glossary - + Announcement TBD - + &obs.ai; @@ -34,7 +34,7 @@ - + API @@ -48,7 +48,7 @@ - + Appliance @@ -58,22 +58,22 @@ Appliances can be copied as-is onto a hard disk, an SSD, or started as a virtual machine (deployed). - - + + - + Archive (Archive File) An archive file contains a representation of usually multiple files and directories. Usually, archive files are also compressed. Archive files are the basis for binary packages - (). + (). - + Attribute @@ -85,7 +85,7 @@ - + Binary Package (Binary) @@ -109,16 +109,16 @@ human-readable like a script, usually does not matter). - sknorr, 2017-08-30 - - - - - - - + + + + + + + - + Branch @@ -127,10 +127,10 @@ repository. You can either delete the branch or merge it into the original repository with a submit request. - + - + Bug @@ -138,7 +138,7 @@ - + Bugowner + + - + Build Requirement @@ -198,18 +198,18 @@ For example, a C++ program needs the C++ compiler included in the gcc package. - - + + - + Build Result The current state of a package. Example of a build result could be succeeded, failed, blocked, etc. - + Build Root @@ -217,10 +217,10 @@ packages. By default, the build root is located in /var/tmp/build-root/BUILD_TARGET. - + - + Build Target @@ -229,7 +229,7 @@ - + Changelog @@ -237,10 +237,10 @@ can contain information about version updates, bug and security fixes, incompatible changes, or changes related to the distribution. - + - + .changes File @@ -248,10 +248,10 @@ In &obsa;, a file with the file extension .changes to store changelog information. - + - + Commit @@ -259,10 +259,10 @@ the author, the date and time, a commit checksum, an optional request number, and a log message. - + - + Container @@ -275,25 +275,25 @@ system. Unlike binary packages, containers are deployed and not installed. Formats of containers include &appimg;, &docker;, &snap;, and &flatpak;. - - - + + + - + Deb A package format created and used by the Debian distribution. - - + + - + Decision @@ -302,18 +302,18 @@ - + Description TBD - + Dependency - + - + Devel Project @@ -321,11 +321,11 @@ the devel project devel:languages:python stores all packages related to the Python programming language. - - + + - + Docker @@ -333,10 +333,10 @@ Docker is a lightweight virtualization solution to run multiple virtual units (containers) simultaneously on a single control host. - + - + Download Repository @@ -348,11 +348,11 @@ - + Diff - + - + DISTURL @@ -384,7 +384,7 @@ - + EULA @@ -395,11 +395,11 @@ - + Fix - + - + Flags @@ -409,15 +409,15 @@ - + GA Project The GA (general availability) project builds an initial release of a product. It gets frozen after releasing the product. All further updates get released via the of this project. + linkend="obs-glos-update-project"/> of this project. - + GPG Key @@ -427,27 +427,27 @@ - + Home Project Working area in OBS for uploading and building packages. Each home project starts with home:USERNAME. - + - + Home Repository TBD - - + + - + Image (Image File) @@ -456,12 +456,12 @@ multiple types of image: - - + + - + Image Description @@ -470,10 +470,10 @@ *.kiwi), scripts, or configuration data to customize certain parts of the &kiwi; build process. - + - + Incident Describes a specific problem and the @@ -482,7 +482,7 @@ maintenance incident project and the update get built here. - + Installation Requirement @@ -491,7 +491,7 @@ - + &kiwi; @@ -499,31 +499,31 @@ create images for Linux supported hardware platforms or for virtualization systems. - + - + License Written contract to specify permissions for use and distribution of software. - + - + Link A concept that defines a relationship between a source and a target repository. - + - + Maintainer @@ -532,26 +532,26 @@ add, modify, and remove packages and subprojects, accept submit requests, and change metadata. - + - + Maintenance Project A project without sources and binaries, defined by the maintenance team. Incidents are created as sub projects of this project. - + - + Maintenance Request TBD - + Metadata @@ -559,7 +559,7 @@ - + &obsa; Package @@ -583,7 +583,7 @@ - + &OBS; @@ -597,15 +597,15 @@ - + &osbs; A specific Web service instance of from the &opensuse; project at + linkend="obs-glos-obs"/> from the &opensuse; project at . - + &osccmd; @@ -613,12 +613,12 @@ stands for openSUSE commander. &osccmd; works similarly to SVN or Git. - + - + Operating System Image @@ -627,20 +627,20 @@ Depending on their purpose, operating system images are classified into: - - - + + + Formats of operating system images include ISO, Virtual Disk, and PXE Root File System. - - - + + + - + Overlay File @@ -652,31 +652,31 @@ system (overlaid) of the appliance root. This includes permissions and attributes as a supplement. - - - + + + - + Package &obsa; handles very different types of software package: - - - + + + - + - + Package Requirement - + - + Package Repository A place where installable packages are available. This can @@ -691,16 +691,16 @@ - + Patch Textual differences between two versions of a file. - + - + Patch File @@ -708,17 +708,17 @@ class="extension">.diff or .patch. - + - + Patchinfo TBD - + Product Image @@ -729,11 +729,11 @@ Live images are a special case of operating system images. They can be run directly a USB disk or DVD and are often but not always installable. - - + + - + Project @@ -742,7 +742,7 @@ - + Project Configuration @@ -750,21 +750,21 @@ on or off certain features during the build or to handle circular dependencies. - + - + Publishing Finished process when a package is successfully built and available in the download repository. - + - + Release Project A release project is hosting a release repository which is not @@ -773,17 +773,17 @@ - + Repository A distribution-specific area that holds dependencies required for building a package. - + - + Repo File @@ -792,56 +792,56 @@ name of the repository, the repository type, and references to the download repository and the GPG key. - + - + Request TBD - + Requirement In the &obsa; context, package requirements that are needed to create, build, or install a package. - - + + - + Revision A unique numeric identifier of a commit. - + - + RPM A package format. It stands for recursive acronym RPM Package Manager. Mainly used by &suse;, Red Hat, u.a. - - + + - + Sandbox Isolated region of a host system which runs either a virtual machine or a change root environment. - + - + Service File @@ -851,7 +851,7 @@ - + Spec File @@ -859,32 +859,32 @@ a general package description and dependencies required for building and installing the package. - - - + + + - + Status Monitor TBD - + Source Original form, mostly written in a computer language. - + - + Source Link - + - + Source Package @@ -897,20 +897,20 @@ An example of source packages are SRPMs which contain the source for accompanying &rpmf; binary packages. - - + + - + Source Service A tool to validate, generate, or modify a source in a trustable way. - + - + &suse; Package Hub @@ -920,14 +920,14 @@ - + System Status TBD - + Submit Request @@ -935,17 +935,17 @@ - + Subproject A child of a parent project. - - - + + + - + Target @@ -956,20 +956,20 @@ - + Update Project A project which provides official updates for the products generated - in the . The update project usually + in the . The update project usually links sources and repositories against the . + linkend="obs-glos-ga-project"/>. - - + + - + Virtual Machine Image @@ -978,12 +978,12 @@ computer and run as-is. As such, there is some overlap between virtual machine images and appliances. - - + + - + Watchlist @@ -992,11 +992,11 @@ - + Working Copy - + - + Working Directory @@ -1007,7 +1007,7 @@ - + &zypper; diff --git a/xml/obs_image_templates.xml b/xml/obs_image_templates.xml index 7efd6949..f0019017 100644 --- a/xml/obs_image_templates.xml +++ b/xml/obs_image_templates.xml @@ -3,14 +3,14 @@ %entities; ]> - Image Templates &image_template_introduction_paragraph; - For more information about &kiwi; images, see . + linkend="kiwi-appliance"/>. @@ -50,7 +50,7 @@ templates. For more information about interconnects, see - . + . diff --git a/xml/osc_building.xml b/xml/obs_local_building.xml similarity index 79% rename from xml/osc_building.xml rename to xml/obs_local_building.xml index 161ee152..30222a26 100644 --- a/xml/osc_building.xml +++ b/xml/obs_local_building.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -12,8 +12,8 @@ - Every build which happens on the server can also be executed locally in the same environment using - the osc tool. All what you need is to checkout the source code and build the build recipe. The + Every build that happens on the server can also be executed locally in the same environment using + the osc tool. All you need is to check out the source code and run osc build to run the build recipe. The following explains it for RPM format, but it works for any. osc will download needed binaries and execute the local build. @@ -21,8 +21,19 @@ toms 2017-08-18: Also integrate content from obs_build_containers.xml - - Generic build options + + Generic Local Build Options + + Frequently, local builds are undertaken on local checkouts of source packages that + already reside on an &obsa; server - for example, to test changes before commiting + them to the server. + + + It is also possible to trigger a local build in an arbitrary local directory containing + sources, without any corresponding source package on an &obsa; server. (However, osc + will still need a connection to the server in order to download build dependencies.) + The following text describes what the source directory should contain, at a minimum. + Independent of the build format you need at least one source file as build description. The file name and structure is format specific. You can find some supported formats described below. @@ -49,13 +60,14 @@ - For existing packages, this is already the case. To build an - existing package, the general procedure is as follows: + In the typical case of source packages locally checked out from an &obsa; + server, this is already the case. To build an existing package, the general + procedure is as follows: If you have not done so yet, set up your project as shown in - . + . @@ -83,8 +95,8 @@ - The simplest way to run a build is just to call the build command. osc will try - to detect your installed OS and build for it if possible. + The simplest way to run a build is just to call the osc build + command. osc will try to detect your installed OS and build for it if possible. &prompt.user;osc build @@ -95,8 +107,7 @@ - It will download the required dependencies and execute the build script. Therefore it needs to ask for root - permissions in most cases. + It will download the required dependencies and execute the build script. Therefore it needs to ask for root permissions in most cases. @@ -141,8 +152,8 @@ The buildroot was: /var/tmp/build-root/openSUSE_Tumbleweed-x86_64 - - Advanced Build Environment Handling + + Advanced Local Build Environment Handling The default build environment for local builds is usually chroot. While this is simplest environment and is therefore easy and fast to handle, it has also a number of shortcomings. For one it is diff --git a/xml/obs_maintenance_setup.xml b/xml/obs_maintenance_setup.xml index 2127ae4f..981c806a 100644 --- a/xml/obs_maintenance_setup.xml +++ b/xml/obs_maintenance_setup.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -50,23 +50,23 @@ start the maintenance process via doing a "maintenance" request. - openSUSE:11.4 is the in + openSUSE:11.4 is the in this example. It is locked and not changing anymore. openSUSE:11.4:Update is the to release official updates for the + linkend="obs-glos-update-project"/> to release official updates for the locked openSUSE:11.4 project. Thus it links to the openSUSE:11.4 project, inheriting all package sources from there. openSUSE:Maintenance is the which in this case maintains + linkend="obs-glos-maintenance-project"/> which in this case maintains the openSUSE:11.4:Update project (and optionally others as well). openSUSE:Maintenance:IDxxx is a project created automatically by accepting a + linkend="obs-glos-incident"/> project created automatically by accepting a maintenance request. @@ -76,17 +76,17 @@ All workflow related projects must be set up with a proper project meta configuration. - It is recommended to lock the by the project maintainer + It is recommended to lock the by the project maintainer by using the osc lock [PROJECT] command - The has to have the <link project="[PROJECT]"/> + The has to have the <link project="[PROJECT]"/> element in the project meta configuration. It is very useful to define groups of bugowners, maintainers and reviewers and to make use of bots for further quality assurance tasks. - The has to have the + The has to have the <project name=... kind="maintenance"> attribute in the project meta configuration, as well as a <maintenance> @@ -118,8 +118,8 @@ osc branch --maintenance openSUSE:12.1 glibc osc branch -M -c openSUSE:12.1 glibc In a simple setup as described before, create the maintenance branch - from the package of the as the - can never be changed anymore. + from the package of the as the + can never be changed anymore. NOTE: both branch commands do support the --noaccess parameter, which will create a hidden project. This may be used when a not yet publicly known security issue is get fixed. diff --git a/xml/obs_moderation.xml b/xml/obs_moderation.xml index a655f951..04e43c14 100644 --- a/xml/obs_moderation.xml +++ b/xml/obs_moderation.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -189,7 +189,7 @@ How To Moderate? As a moderator you can click on the yellow warning about reports, usually displayed close to the element. - There, you can read all the reports and make a . Write the reason why you agree (Favor) or disagree (Cleared). + There, you can read all the reports and make a . Write the reason why you agree (Favor) or disagree (Cleared).
@@ -245,12 +245,12 @@ - Most of these actions are reversible. Read section . + Most of these actions are reversible. Read section . - + Reverting Moderator's Actions Most of these actions are reversible except for removing a comment. @@ -269,7 +269,7 @@ In case the moderator changes their mind, they can revert the actions they made. - Read section . + Read section .
diff --git a/xml/obs_motivation.xml b/xml/obs_motivation.xml index 6b2c8379..1948b400 100644 --- a/xml/obs_motivation.xml +++ b/xml/obs_motivation.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -14,7 +14,7 @@ - + Motivation The basic challenge when distributing Free and Open Source Software @@ -39,7 +39,7 @@ - + Goals and Target Groups for &obsa; The goals of the OBS are oriented towards the three groups of people that use it: @@ -67,7 +67,7 @@ - + Automated Software Builds for Packagers For people who contribute to the Free Software community by packaging @@ -78,7 +78,7 @@ - + Reproducibility for Free Software Projects and Independent Software Vendors (ISV) &obsa; emphasizes on making builds reproducible. It builds packages in a jailed environment that &obsa; sets up from scratch each time. When the @@ -99,7 +99,7 @@ - + Easy Access to Software for Users The OBS aims to make it easy for users to download the latest version of software as binary packages for their operating system. They do not have diff --git a/xml/obs_multibuild.xml b/xml/obs_multibuild.xml index 2e34fdc6..eabe7e67 100644 --- a/xml/obs_multibuild.xml +++ b/xml/obs_multibuild.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_notifications.xml b/xml/obs_notifications.xml index 4433051d..db11329a 100644 --- a/xml/obs_notifications.xml +++ b/xml/obs_notifications.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -35,7 +35,7 @@ notifications and mark them as read, improving your OBS workflow experience. - + Notifications Configuration Click on the "Manage Your Notifications" link to define which notifications @@ -86,7 +86,7 @@
- + Where Can We Find the Notifications? At the top right corner of every page, you will find a link to your @@ -105,7 +105,7 @@
- + Notifications Content After clicking on the "Notifications" link, you will see a list of your most @@ -128,7 +128,7 @@ - + Mark Notification as Read or Unread Once you read a notification and possibly take action, you can mark it as @@ -198,7 +198,7 @@ - + Notifications Filters Filters help you in focusing your attention on a subset of your @@ -287,7 +287,7 @@ - + API Every user can check their unread notifications by querying: diff --git a/xml/obs_osc.xml b/xml/obs_osc.xml index b8f53242..be2fd229 100644 --- a/xml/obs_osc.xml +++ b/xml/obs_osc.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -19,7 +19,7 @@ toms 2017-08-16: http://docserv.suse.de/documents/Open_Build_Service/obs-best-practices/html/cha.obs.best-practices.oscexamples.html#id17157 osc, the Python command line client - + Installing and Configuring<!-- the &osc; CLI Tool--> toms 2017-08-17: Integrate some sections/text from here http://docserv.suse.de/documents/Open_Build_Service/obs-best-practices/html/cha.obs.best-practices.localsetup.html @@ -43,7 +43,7 @@ ~/bin directory, and make the file executable. - + Configuring &osc; Usually, the default configuration is appropriate in most cases. There are some special configuration option which might be helpful @@ -147,10 +147,10 @@ - + Usage - + Getting Help @@ -164,7 +164,7 @@ - + Using &osccmd; for the First Time When you use the &osccmd; command for the first time, the command will @@ -206,7 +206,7 @@ authenticated it. - + Overview of Brief Examples The &osccmd; command is similar to git: @@ -236,7 +236,7 @@ Which &obsa; instance it shows depends on the option in the configuration file. By default, the &opensuse; Build Server is used. If you need another server, use the - option as shown in . + option as shown in . diff --git a/xml/obs_package_formats.xml b/xml/obs_package_formats.xml index 9f4e0d93..4721861f 100644 --- a/xml/obs_package_formats.xml +++ b/xml/obs_package_formats.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -176,7 +176,7 @@ --> - + &kiwi; Appliance KIWI is an OS @@ -286,7 +286,7 @@ systemctl enable sshd toms 2017-08-18: TODO What is it and what is needed - + &flatpak; The Flatpak format can be used @@ -418,7 +418,7 @@ Support: kmod-compat kernel-default perl-YAML-LibYAML - + mkosi Mkosi allows diff --git a/xml/obs_preface.xml b/xml/obs_preface.xml index af0ea612..fd13341c 100644 --- a/xml/obs_preface.xml +++ b/xml/obs_preface.xml @@ -17,10 +17,6 @@ This guide does not focus on a specific &obsa; version. - - That is hogwash: It just documents whatever was available at the time of - writing. - sknorr, 2017-08-23 - It is also not a replacement of the documentation inside of the &opensuse; Wiki. However, content from the wiki may be included in diff --git a/xml/obs_product_building.xml b/xml/obs_product_building.xml index 51559388..47339dd2 100644 --- a/xml/obs_product_building.xml +++ b/xml/obs_product_building.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_qa_hooks.xml b/xml/obs_qa_hooks.xml index f5cc2976..3ca28f83 100644 --- a/xml/obs_qa_hooks.xml +++ b/xml/obs_qa_hooks.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_request_and_review_system.xml b/xml/obs_request_and_review_system.xml index 93cbf513..aa45e4d6 100644 --- a/xml/obs_request_and_review_system.xml +++ b/xml/obs_request_and_review_system.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_scheduling_and_dispatching.xml b/xml/obs_scheduling_and_dispatching.xml index 8c3a8888..177ff0a8 100644 --- a/xml/obs_scheduling_and_dispatching.xml +++ b/xml/obs_scheduling_and_dispatching.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_scm_bridge.xml b/xml/obs_scm_bridge.xml index e2f660d3..b722fac8 100644 --- a/xml/obs_scm_bridge.xml +++ b/xml/obs_scm_bridge.xml @@ -3,7 +3,7 @@ %entities; ]> - SCM Bridge - + SCM Bridge - + Introduction The SCM bridge allows the sources of a single package or an entire project @@ -44,7 +44,7 @@ allow OBS to follow the sources automatically. - + Setup a package using the scm bridge The setup is purely done in package meta by defining the SCM URL inside of the scmsync tag: @@ -67,7 +67,7 @@ - + Setup an entire project using the SCM bridge An entire project can be setup by defining the scmsync tag in project meta data. Every top level @@ -85,7 +85,7 @@ <scmsync>https://gitlab.com/some/repository?onlybuild=glibc&onlybuild=kernel</scmsync> - + Implementation and Limitations The sources are currently cloned for the OBS source server to allow OBS to process them. This @@ -112,7 +112,7 @@ <scmsync>https://gitlab.com/some/repository?subdir=MY_SUBDIRECTORY</scmsync> - + Using a specific revision, tag or branch The URL can define a revision, tag or branch via an URL fragment. This means the URL can get extended by a @@ -126,7 +126,7 @@ - + Converting to a project git A project git repository is mostly the same as any project for the pbuild tool. The command # osc create-pbuild-config @@ -137,7 +137,7 @@ - + Forking a scmsync package The OBS server allows to create a cloned project with another package using a specified SCM repository. This can be used by tooling to create forked test builds for merge requests. @@ -148,11 +148,11 @@ - + SCM Source Updates The OBS instance needs to get notified on any change in the SCM server. There are two ways to achieve this. - One way is via single configurations for each git repository as documented in the documentation. + One way is via single configurations for each git repository as documented in the documentation. An alternative way is to configure it globally. This requires admin permissions on the git hosting side and another bridge implementation. The advantage is that any used repository will be synced automatically just by referencing it via the scmsync meta tag. diff --git a/xml/obs_scm_ci_workflow_integration.xml b/xml/obs_scm_ci_workflow_integration.xml index 3c7893e4..0d5094d9 100644 --- a/xml/obs_scm_ci_workflow_integration.xml +++ b/xml/obs_scm_ci_workflow_integration.xml @@ -3,7 +3,7 @@ %entities; ]> - SCM/CI Workflow Integration - + SCM/CI Workflow Integration Setup - + Introduction With this integration, you can take advantage of source code management (SCM) @@ -33,11 +33,11 @@ constantly mentioning all the names for the same things, e.g. Pull Requests/Merge Requests, is tiresome and confusing. However, every aspect has its correspondence in GitLab and Gitea. Refer to + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-equivalence-table"/> for clarification of terminology. - + Prerequisites Before you start, you need to @@ -53,7 +53,7 @@ - + Supported SCMs We support the GitHub.com and GitLab.com instances. @@ -63,13 +63,13 @@ with that SCM. - + Token Authentication OBS and GitHub need to talk to each other. Tokens are the way to make this happen. - + How to Authenticate OBS with SCMs You have to create a GitHub personal @@ -115,14 +115,14 @@ documentation to learn how. - + How to Authenticate SCMs with OBS You have to create an OBS workflow token. Github is going to use it to trigger actions on OBS on your behalf. - + Create Token You can create the OBS token via WebUI in Profile @@ -144,14 +144,14 @@ Make sure you replace long_ascii_salad with your real GitHub personal access token created in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication-how-to-authenticate-obs-with-scm"/> Don't forget to keep your token secret to prevent someone else from triggering operations in your name! - + Regenerating Secrets and Deleting Tokens If you suspect your OBS token secret was leaked, you can regenerate @@ -174,19 +174,19 @@ osc token --delete $token_id # remove the token with the given id Then you can create a new one as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication-how-to-authenticate-scm-with-obs"/> and replace it wherever you use it. - + Webhooks Once OBS and GitHub are allowed to speak to each other, they can start talking via webhooks. - + SCM Events On a GitHub repository, events are happening all the time: a @@ -264,7 +264,7 @@ - Refer to the for more details or read more about Refer to the for more details or read more about GitHub events, GitLab @@ -274,7 +274,7 @@ events. - + How to Set Up a Webhook on Github Go to the project you want to set the integration on, then under @@ -322,7 +322,7 @@ - + How to Set Up a Webhook on GitLab Go to the project you want to set the integration on, under @@ -362,7 +362,7 @@ - + How to Set Up a Webhook on Gitea Go to the repository you want to set the integration on, then under @@ -411,7 +411,7 @@ - + OBS Workflows A GitHub event occurs and OBS receives the corresponding webhook. @@ -427,7 +427,7 @@ a directory .obs which contains a file called workflows.yml. If you don't want to use that directory, you should check - out. + out. The content of .obs/workflows.yml could look @@ -465,7 +465,7 @@ rebuild_master: only: - master - + Configuration File Location By default the configuration file is fetched from the repository's @@ -498,7 +498,7 @@ rebuild_master:
- + OBS Workflow Steps We support the following steps (the keys used in the @@ -540,7 +540,7 @@ rebuild_master: branch a package, link packages, configure repositories/architectures, rebuild packages and trigger services of a package. - + Branch a Package in a Project Given we have a source package called @@ -581,7 +581,7 @@ rebuild_master: configure_repositories step, set the add_repositories key to anything else than enabled. - + Submit a Request The submit request step is the equivalent of the osc submitrequest command. @@ -628,7 +628,7 @@ rebuild_master: description: 'Check out this cool package' # (optional, uses the commit/pull request message if not set) - + Link a Package to a Project The link package step is the equivalent of osc @@ -670,13 +670,13 @@ rebuild_master: target_project: home:jane - If you rely on + If you rely on to run, for instance to pick up changes from a PR with the obs_scm service, you can't make use of this step. Package links do not run the services. Use the branch_package step instead. - + Configure Repositories/Architectures for a Project Given a project called home:jane, the step will @@ -741,7 +741,7 @@ rebuild_master: - x86_64 - + Rebuild a Package Given a project called home:Admin and a @@ -758,12 +758,12 @@ rebuild_master: package: ctris - + Set Flags for Projects, Packages, Repositories or Architectures There are OBS-wide defaults for each flag type. This step is only necessary if you want to diverge from the defaults (see - ). + ). Providing the type build, the status enable and the project home:Admin, OBS will enable all builds: @@ -797,7 +797,7 @@ rebuild_master: set_flags step, although this isn't necessary as long as they exist. The type has to be one of the following values: - + Valid flag types lock (default status disable) build (default status enable) @@ -831,7 +831,7 @@ rebuild_master: architecture: x86_64 - + Trigger Services of a Package Given a project called home:Admin and a @@ -851,7 +851,7 @@ rebuild_master: - + Filters You can customize when workflows run by declaring @@ -874,7 +874,7 @@ rebuild_master: - master - staging - + Filters Delimiters: only and ignore Some steps can affect a group of elements (branches) @@ -930,11 +930,11 @@ rebuild_master: - staging - + Event Filter Setting an event filter will run the workflow only for this event. The event filter doesn't accept multiple events. - Documentation on the SCM events can be found here: . + Documentation on the SCM events can be found here: . The available event filters are: @@ -946,7 +946,7 @@ rebuild_master: merge_request is an alias for the - 'pull_request' event. Introduced with workflow version 1.1 (also see ). + 'pull_request' event. Introduced with workflow version 1.1 (also see ). . @@ -974,7 +974,7 @@ rebuild_master: event: pull_request - + Branches Filter Matches target branches based on their names and runs a @@ -997,7 +997,7 @@ rebuild_master: - final Learn more about . + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-filters-delimiters"/>. @@ -1008,7 +1008,7 @@ rebuild_master: - + Placeholder Variables With placeholder variables, workflows are now dynamic. Whenever a @@ -1057,11 +1057,11 @@ test_build: For a more in-depth example in combination with configuration file location, refer to - . + . - + Status Reporting Once all the steps in the workflow are done, OBS will report the build results back to GitHub. @@ -1102,7 +1102,7 @@ test_build: - + Workflow Runs For every SCM event, OBS compiles relevant information about the workflows running on the system. You can find the @@ -1172,7 +1172,7 @@ test_build: the workflow run will record error messages. And reading the artifacts will help to understand what happened behind the scenes. - + Errors
@@ -1225,7 +1225,7 @@ test_build:
- + Equivalence Table @@ -1282,7 +1282,7 @@ test_build: - + SCM/CI Workflow Steps Reference Table For each step, this table shows which event on the SCM will trigger which operations on the OBS. @@ -1510,7 +1510,7 @@ test_build:
- + SCM/CI Workflow Versions To secure the compatibility of SCM/CI workflows with new features and changes, we are introducing those through new versions. We specify them with a - + Workflow Version Table Current available workflow versions and the introduced changes can be found in the versions table below. @@ -1561,10 +1561,10 @@ test_build: - + SCM/CI Workflow Integration Use-Cases - + OBS SCM Service For some of the use cases, you might want the OBS package to get @@ -1578,7 +1578,7 @@ test_build: it. - + Test Build a Package For Every Pull Request on GitHub You decide to manage your package sources from a GitHub @@ -1586,7 +1586,7 @@ test_build: sources by opening a pull request, you need to verify that your package still builds for certain repositories and architectures in OBS. You can have the best of both worlds with the . + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/>. You will need: @@ -1612,24 +1612,24 @@ test_build: The required tokens to allow OBS and GitHub talk each other as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication"/> The required webhooks so GitHub notifies OBS of any event as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-webhooks"/> This is obviously a good candidate to use the . + linkend="sec-obs-obs-scm-ci-workflow-integration-use-cases-service"/>. There are two different strategies to do this: branching the package or linking to it. - + Branch If you decide to branch the package for the test build, the @@ -1658,12 +1658,12 @@ test_build: package will be deleted. Read and, + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/> and, specifically, the workflow steps (). + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-steps"/>). - + Link and Configure Repositories If you prefer to link the package for the test build, the @@ -1704,13 +1704,13 @@ test_build: flexibility to decide which repositories are you interested in. Read and, + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/> and, specifically, the workflow steps (). + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-steps"/>). - + Rebuild a Package for Every Change in a Branch You have a test build set up and you want it to keep up to date @@ -1733,18 +1733,18 @@ test_build: The required tokens to allow OBS and GitHub talk each other as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication"/> The required webhooks so GitHub notifies OBS of any event as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-webhooks"/> The source code synchronization setup with the . + linkend="sec-obs-obs-scm-ci-workflow-integration-use-cases-service"/>. @@ -1759,7 +1759,7 @@ test_build: event: push - + Set Flags on a Package to Disable Builds for an Architecture When you branch a package, all its repositories and their architectures will be copied over. @@ -1784,7 +1784,7 @@ test_build: - + Create Package on OBS for Every Software Release With Git Tags You have a software project for which you mark releases with Git tags. For every release, you want to create @@ -1795,7 +1795,7 @@ test_build: versioned releases to another project on OBS if you need it as a dependency. After the usual setup for - OBS workflows with tokens and webhooks (see ), you will need: + OBS workflows with tokens and webhooks (see ), you will need: @@ -1894,7 +1894,7 @@ test_build: - + Using a Custom Configuration File URL in Combination with Placeholder Variables It may happen that you have multiple repositories following the same @@ -1934,14 +1934,14 @@ test_build: From here the only thing left to do would be to host this file somewhere where OBS can access it, creating a workflow token and the - corresponding webhooks (following the setup instructions at ) + corresponding webhooks (following the setup instructions at ) for every SCM repository you want this configuration file to apply to, - making sure you set the correct configuration url (see ). + making sure you set the correct configuration url (see ). There are many other ways to use these two features in parallel, make sure to read - - and + + and to get some inspiration on how you can use them in your project. diff --git a/xml/obs_signing.xml b/xml/obs_signing.xml index e6075b63..b974edb3 100644 --- a/xml/obs_signing.xml +++ b/xml/obs_signing.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_source_management.xml b/xml/obs_source_management.xml index 38389ea3..24ad302d 100644 --- a/xml/obs_source_management.xml +++ b/xml/obs_source_management.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -54,7 +54,7 @@ OBS 2.11 can produce and publish additional SPDX data for certain build types. This is controlled via the project configuration. For details, refer to - for + for sbom:FORMAT (under BuildFlags). diff --git a/xml/obs_source_service.xml b/xml/obs_source_services.xml similarity index 83% rename from xml/obs_source_service.xml rename to xml/obs_source_services.xml index 19cedfa8..28c4f907 100644 --- a/xml/obs_source_service.xml +++ b/xml/obs_source_services.xml @@ -3,15 +3,15 @@ %entities; ]> - Using Source Services - - About Source Service + + About Source Services Source Services are tools to validate, generate or modify sources in a trustable way. They are designed as smallest possible tools and can be @@ -23,8 +23,8 @@ - Server side generated files are easy to identify and are not - modifiable by the user. This way other user can trust them to be + Server-side generated files are easy to identify and are not + modifiable by the user. This way, other users can trust them to be generated in the documented way without modifications. @@ -40,48 +40,48 @@ - Services are runnable at any time without user commit. + Source services are runnable at any time without user commit. - Services are runnable on server and client side in the same way. + Source services are runnable on server and client side in the same way. - Services are safe. A source checkout and service run never harms + Source services are safe. A source checkout and service run never harms the system of a user. - Services avoid unnecessary commits. + Source services avoid unnecessary commits. This means there are no time-dependent changes. In case the package - already contains the same file, the newly generated file are dropped. + already contains the same file, the newly generated file is dropped. - Services running local or inside the build environment can get created, + Source services running local or inside the build environment can get created, added and used by everybody. - Services running in default or server side mode must be installed by + Source services running in default or server side mode must be installed by the administrator of the &obsa; server. - The use of a service can be defined per package or project wide. + The use of a source service can be defined per package or project wide. For using source services you need (refer to ): + linkend="ex-obs-sserv-struct"/>): @@ -101,34 +101,34 @@ - + Structure of a <filename>_service</filename> File - <services> - <service name="MY_SCRIPT" mode="MODE"> - <param name="PARAMETER1">PARAMETER1_VALUE</param> + <services> + <service name="MY_SCRIPT" mode="MODE"> + <param name="PARAMETER1">PARAMETER1_VALUE</param> </service> </services> - + The root element of a _service file. - + The service name. The service is a script that is stored in the /usr/lib/obs/service directory. - + - Mode of the service, see . + Mode of the service, see . - + One or more parameters which are passed to the script defined in - . + . @@ -142,13 +142,13 @@ services from /usr/lib/obs/service/? - - Modes of Services - Each service can be used in a mode defining when it should run + + Modes of Source Services + Each source service can be used in a mode defining when it should run and how to use the result. This can be done per package or globally for an entire project. - Service Modes + Source Service Modes @@ -192,7 +192,7 @@ buildtime - During each build before calling the build tool (for example, rpm-build) + During each build before calling the build tool (for example, rpm-build) A side effect is that the service package is becoming a build dependency and must be available. @@ -298,10 +298,10 @@ - - Defining Services for Validation + + Defining Source Services for Validation - Source Services can be used to validate sources. This can be defined + Source services can be used to validate sources. This can be defined at different levels: @@ -351,7 +351,7 @@ - + Creating Source Service Definitions Source services are defined in the _service file @@ -397,7 +397,7 @@ - + Removing a Source Service Sometimes it is useful to continue working on generated files manually. In this situation the _service file needs @@ -408,32 +408,32 @@ osc service merge. - + Trigger a service run via a webhook You may want to update sources in &obs; whenever they change in a SCM system. You can create a token which allows to trigger a specific package update and use it via a webhook. It is recommended to create a token for a specific package and not a wildcard token. - Read to learn how to + Read to learn how to create a token. - - Using it on gitlab + + Creating a webhook on GitLab - Go to your repository settings page in your gitlab instance. Select Integrations - there. All what you need to fill is the URL + Go to your repository settings page in your gitlab instance. Select Integrations + there. All what you need to fill is the URL https://YOUR_INSTANCE/trigger/runservice - and the Secret Token. Hit the Add webhook button and you are good. - You may specify project and package via CGI parameters in case you created a - wildcard token: + and the Secret Token. Hit the Add webhook button and you are good. + You may specify project and package via CGI parameters in case you created a + wildcard token: https://YOUR_INSTANCE/trigger/runservice?project=PROJECT&package=PACKAGE - - Using it on github.com + + Creating a webhook on GitHub Go to your repository settings page of your repository on github.com. Select Webhooks settings and create a hook via Add Webhook button. Define the payload @@ -448,8 +448,4 @@ - - Interfaces for Using Source Services - tbd - diff --git a/xml/obs_staging_workflow.xml b/xml/obs_staging_workflow.xml index 6a27ef5f..1cde3eae 100644 --- a/xml/obs_staging_workflow.xml +++ b/xml/obs_staging_workflow.xml @@ -4,12 +4,12 @@ %entities; ]> - Staging Workflow - + Working with Staging Projects This API provides an easy way to get information about a single or all staging projects like @@ -17,7 +17,7 @@ Note: To use this API, you first need to setup a staging workflow for a project. - + Overview of All Staging Projects This endpoint provides an overview of all staging projects for a certain project. @@ -79,7 +79,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects/? - + Overview of a Single Staging Project This endpoint provides an overview of a single staging project. @@ -122,7 +122,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects// - + Copy a Staging Project This endpoint creates a copy of a staging project. It will queue a job which is going to copy the project configuration, repositories, groups and users. @@ -133,11 +133,11 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/staging_pr - + Working with Requests One of the main features of the staging workflow is assigning incoming requests to different staging projects. - + Assign Requests into a Staging Project Our main project openSUSE:Factory received requests with id 1 and 2. @@ -149,7 +149,7 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/staging_pr - + Remove Requests from a Staging Project When we are done with testing the staging project openSUSE:Factory:Staging:A, we need to remove the requests 1 and 2 again. @@ -160,7 +160,7 @@ geeko > osc api -X DELETE '/staging/openSUSE:Factory/staging_ - + List Requests of a Staging Project Listing all requests which are currently assigned to openSUSE:Factory:Staging:A can be done with the following command. @@ -181,7 +181,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects/o - + Exclude Requests for a Staging Workflow Our main project openSUSE:Factory received requests with id 3 and 4. @@ -192,7 +192,7 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/excluded_r - + Bring Back Excluded Requests from a Staging Workflow The following command will stop excluding requests with id 3 and 4 for the staging workflow project openSUSE:Factory. @@ -202,7 +202,7 @@ geeko > osc api -X DELETE '/staging/openSUSE:Factory/excluded - + Accept Staging Project Once all the requests are ready and the staging project has an acceptable state, the requests can be merged. In other words, the staging project can be accepted. diff --git a/xml/obs_supported_formats.xml b/xml/obs_supported_formats.xml index 567ab82a..6af38099 100644 --- a/xml/obs_supported_formats.xml +++ b/xml/obs_supported_formats.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -14,7 +14,7 @@ This chapter is focusing on describing &obs; specifics of a format. Either limitations or extensions of &obs; builds. - + Spec File Specials (RPM) To create an RPM package, you need a spec file. diff --git a/xml/obs_user_concept.xml b/xml/obs_user_concept.xml index 63c54012..dffbc796 100644 --- a/xml/obs_user_concept.xml +++ b/xml/obs_user_concept.xml @@ -4,7 +4,7 @@ %entities; ]> -