dist
Folders and files
Name | Name | Last commit date | ||
---|---|---|---|---|
parent directory.. | ||||
This file briefly describes how to setup an Open Build Service (OBS) with the rpm packages from the openSUSE project. By default all services run on the same system. This document does not describe how to distribute them to increase reliability and do load balancing, but this is possible. An easier way to run OBS is via using the OBS Appliance. It is also usable for a production server. Please find details here: http://wiki.opensuse.org/openSUSE:Build_Service_Appliance 1. Run the backend ================== The backend hosts all sources and built packages. It also schedules the jobs. You need to install the "obs-server" package for this. 1.1 Start the following services in this order ============================================== WARNING: The following commands start services which are accessible from the outside. Do not do this on a system connected to an untrusted network or make sure to block the ports with a firewall. rcobsrepserver start rcobssrcserver start rcobsscheduler start rcobsdispatcher start rcobspublisher start The data gets stored inside the /srv/obs directory by default. 1.2 Start the following optional services ========================================= You may start rcobssigner start in case you want to use the automatic package signing features. You may start rcobswarden start in case you want to monitor your workers 2. Start the workers ==================== The workers ask the backend for open build jobs and do the build. You need to install the "obs-worker" package for this. 2.1 Local worker ================ A worker can be started on localhost by calling rcobsworker start 2.2 Setup multiple workers on remote systems ============================================ A worker can be started on other machines in your network (on the Internet too, but you should have a really fast Internet connection ;-)). You must install the package "obs-worker" on this machine and change some configuration files on both systems. 2.2.1 Necessary changes on machine *main* machine ================================================= Please check /usr/lib/obs/server/BSConfig.pm on the main machine. By default, the local hostname is used. 2.2.2 Necessary changes on worker machine ========================================= If you have installed the package "obs-worker", edit the file /etc/sysconfig/obs-server to change the variable OBS_REPO_SERVERS to "main.fqdn:5252" where "main.fqdn" is the output of "hostname -f" or the IP of the machine where the repserver is running. 3. Run the api ============== You need to install the "obs-api" package for this and a MySQL server on this or a remote host. When using SLE11, the needed packages are only available after adding the SDK to the available installation repositories. 3.1 Setup and configure the MySQL database ========================================== 3.1.1 Initialize fresh Database ============================= * start the MySQL database rcmysql start # use "insserv mysql" for permanent start If you do this for the first time, MySQL will initialize itself and ask to create a root password in the database. After starting mysql for the first time, run the program mysql_secure_installation If you want to give the "root" user the rights to always access your mysql database, create a file "/root/.my.cnf" with the following content: [client] user = root password = foobar [mysqladmin] user= root password = foobar Make sure that this file has the correct permissions with the command: chmod 0600 /root/.my.cnf * Create the empty production databases: # mysql -u root -p mysql> create database api_production; mysql> quit * If you use the MySQL database for other services, too, then it's recommended to add a separate MySQL user, e.g. "obs", like this: # mysql -u root -p'your-password' mysql> create user 'obs'@'%' identified by 'obspassword'; mysql> create user 'obs'@'localhost' identified by 'obspassword'; mysql> GRANT all privileges ON api_production.* TO 'obs'@'%', 'obs'@'localhost'; mysql> FLUSH PRIVILEGES; mysql> quit * Configure your MySQL user and password in in the "production" section of the api config: /srv/www/obs/api/config/database.yml A template for this file can be found in same directory as "database.yml.example". * populate the database cd /srv/www/obs/api/ sudo RAILS_ENV="production" rake db:setup sudo RAILS_ENV="production" rake writeconfiguration sudo chown -R wwwrun.www log tmp 3.2 Setup and configure apache2 for the api and webui ===================================================== Now we need to configure the webserver. By default, you can reach the familiar web user interface and also api both on port 443 speaking https. Repositories can be accessed via http on port 82 (once some packages are built). An overview page about your OBS instance can be found behind http://localhost The obs-api package comes with a apache vhost file, which does not need to get modified when you stay with these defaults: /etc/apache2/vhosts.d/obs.conf Install the required packages via zypper in obs-api apache2 apache2-mod_xforward rubygem-passenger-apache2 memcached Add the follwing apache modules in /etc/sysconfig/apache2: APACHE_MODULES="... passenger rewrite proxy proxy_http xforward headers socache_shmcb" Enable SSL in /etc/sysconfig/apache2 via APACHE_SERVER_FLAGS="SSL" Generate an ssl certificate via following commands: mkdir /srv/obs/certs openssl genrsa -out /srv/obs/certs/server.key 1024 openssl req -new -key /srv/obs/certs/server.key \ -out /srv/obs/certs/server.csr openssl x509 -req -days 365 -in /srv/obs/certs/server.csr \ -signkey /srv/obs/certs/server.key -out /srv/obs/certs/server.crt cat /srv/obs/certs/server.key /srv/obs/certs/server.crt \ > /srv/obs/certs/server.pem To allow the usage of https api in webui code you need to trust your certificate as well: cp /srv/obs/certs/server.pem /etc/ssl/certs/ c_rehash /etc/ssl/certs/ 3.2.2 Change /srv/www/obs/api/config/options.yml ================================================ If you change the hostnames/ips of the api, you need to adjust "frontend_host" accordingly in /srv/www/obs/api/config/options.yml You should set "exception_recipients" to a valid mail address which should receive notification mail if the API hits any program exception. It is recommended to enable use_xforward: true as well here. 3.2.3 Restart apache2 ===================== Afterwards you can start the OBS web api via rcapache2 start # use "insserv apache2" for permanent start rcobsapidelayed start # use "insserv obsapidelayed" for permanent start rcmemcached start # use "insserv memcached" for permanent start 4. Setup initial distributions ============================== The easiest way is reuse a base distro hosted at openSUSE.org. The Open Build Service has a mechanism to reuse projects from a remote instance since version 0.9. It is recommended to use this mechanism. 4.1 Reuse projects hosted on openSUSE.org build service ======================================================= Create the reference project pointing to the openSUSE.org build service. This will allow you to reuse the base distributions from there and avoids further manual setup. You can do this via clicking on the "Configuration" link in your web interface on the main page. Only Admin users do see that link. The alternative manual way is to call the following command: curl -0 --user "Admin:opensuse" -X PUT \ -T /usr/share/doc/packages/obs-api/openSUSE.org.xml \ https://localhost:443/source/openSUSE.org/_meta If you created a self-signed certificate as described above, also add the option "--insecure". 5. Access ========= By default you can access the OBS server using any browser or osc CLI too using the URL https://$servername The default user is "Admin" with the password "opensuse". 5.1 Changing the default URLs ============================= To change the default URLs of the api, configure the lighttpd vhosts accordingly. Edit /etc/apache2/vhosts.d/obs.conf and add the new virtual hostnames. 6. Using osc with your local build service: =========================================== In order to use the command line tool for the build service, run osc with osc -A https://your_server ls for example. osc asks the first time for a user and password pair. 6.1. Test build =============== You can do a test build like this (for example, in a svn checkout of the current openSUSE build server, in the buildservice/dist subdir): Add an "OBS:Server:2.4" project with an "obs-server" package. The following commands offer you a template project or package description file. In the self-explanatory xml, only enable the 10.2 distro on i586: osc -A http://$servername:81 meta prj OBS:Server:2.4 -e Check whether that worked on http://$servername/project/list_all Do the same for the package: osc -A http://$servername:81 meta pkg OBS:Server:2.4 obs-server -e Check whether that worked on http://$servername/project/show?project=openSUSE%3ATools Now prepare for a check-in. This will do a checkout and locally build using the packages from your local buildserver: OSCOPT="-A http://$servername:81" ./distribute now do a check-in into the build server: cd OBS:Server:2.4/obs-server osc add * osc ci The rebuild will automatically be triggered. Monitor the build status here: http://localhost/project/monitor?project=openSUSE%3ATools or via osc, in the same directory as indicated above, with the command: osc r 6.2. Run and Stop the Service ============================= To start and stop everything you can use the following command sequences: rcmysql start rcmemcached start rcobsrepserver start rcobssrcserver start rcobsscheduler start rcobsworker start rcobsdispatcher start rcobspublisher start rcapache2 start rcobsapidelayed start rcapache2 stop rcobsapidelayed stop rcobspublisher stop rcobsdispatcher stop rcobsworker stop rcobsscheduler stop rcobssrcserver stop rcobsrepserver stop rcmemcached stop rcmysql stop To automatically start everything at system boot you can use the following: chkconfig --add mysql obssrcserver obsrepserver obsscheduler \ obspublisher obsdispatcher obsworker \ apache2 Use "chkconfig --del" analogously to no longer automatically start them at boot. 6.3 Optional services ===================== The following service are optional: * obswarden It checks if build hosts are dying and cleans up hanging builds * obssigner It is used to sign packages via the obs-sign daemon. You need to configure it in BSConfig.pm before you can use it. * obsservice This is the source service daemon. Older versions of OBS (<= 1.7) just came with a download service. Newer versions include a couple of "obs-service-*" packages that can be installed separately. This feature is considered to be experimental so far, but can be already extended with own services. The following runlevel scripts are only running on the OBS Appliance for auto configuration: * obsstoragesetup Configures storage volumes based on LVM partitions automatically. * obsapisetup Updates automatically the database layout and configures the web server automatically based on your network setup. 7. Feedback =========== Please send feedback about this file or the packages to opensuse-buildservice@opensuse.org 8. Miscellaneous notes ===================== * logs are located in various directories. apache2: /var/log/apache2 obs: /srv/obs/log api: /srv/www/obs/api/log