OpenData CKAN VM for Microsoft Azure Installation / First Steps Stand: 26.11.2015 Version: 1.2 Status: translated OpenData-CKAN@Azure_Manual_en_v1.2.docx 1 / 12
1 Disclaimer Thank you for using CKAN and Microsoft Azure for your Open Data project. This document provides you with an overview on how to install, how to set up and how to use the Azure based CKAN image provided by Teleport. This system software is provided as is and any expressed or implied warranties, including, but not limited to, the implied warranties, including, but not limited to the implied warranties of merchantibility and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, special, exemplary or consequential damages (including, but not limited to procurement of substitute goods or services; loss of use, data or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. 2 Installation Notes 2.1 Web Server The CKAN Server is ready to use right after the installation on the Azure-based virtual machine. The CKAN front-end can be reached via the URL that is provided by Azure (http://yourdomain.cloudapp.net/) or a customised URL respectively. CKAN will be delivered by an Apache web server via an Nginx-Proxy. Respective standard directories are used for applications and configuration. For administration purposes it is needed to establish a CKAN system administrator account (se also chapter 2.4). 2.2 Access via SSH By default, SSH access is possible via port 22 using the specified password. User name and password can be chosen when configuring the virtual machine (VM). 2.3 Setting up the Firewall When delivered, a firewall is configured on the system. This firewall exclusively enables those connections which are necessary for operating the CKAN server (Port 80 and 22). If you plan to operate additional services on the virtual machine you need to configure the firewall respectively. 2.4 Setting up the System Administrator Account The CKAN administrator account is needed for operating the CKAN server. Its set up is part of the basic installation and uses the following log-in data: OpenData-CKAN@Azure_Manual_en_v1.2.docx 2 / 12
Benutzername (Account): admin Kennwort (Password): abc1234 Important Note: For security reasons, please use the initial account for logging into the front-end and change the initial password immediately! If you need further system admin accounts, you need to set them up via command line interface and ssh respectively. After having logged in via ssh, you need to execute the following commands: This example establishes a second system admin with the name ckanadmin2. Using the system admin account you can specify users, datasets and organizations.. /usr/lib/ckan/default/bin/activate cd /usr/lib/ckan/default/src/ckan paster sysadmin add ckanadmin2 -c /etc/ckan/default/production.ini OpenData-CKAN@Azure_Manual_en_v1.2.docx 3 / 12
2.5 Changing Site Title and Logo Editing the standard configuration file /etc/ckan/default/production.ini the following components can be edited and substituted respectively: Site title (ckan.site_title) Site description (ckan.site_description) Site logo (ckan.site_logo) CSS and Templates (extra_public_paths) A more comfortable option provides the web interface that can be accessed choosing Sysadmin- Einstellungen > Konfiguration ( Sysadmin-Settings > Configuration ) Using this interface, you can also maintain information provided via the web page Über uns ( About ). Also, you can edit the text of the start page. Hint: the file path for the site logo is /usr/lib/ckan/default/src/ckan/ckan/public 2.6 Site Language Multi-language support is provided for the CKAN server. You can choose the language in the lower part of the browser window. OpenData-CKAN@Azure_Manual_en_v1.2.docx 4 / 12
As of today, German language is supported. If you want to change the standard language or to extend the set of languages, you can edit the configuration file /etc/ckan/default/production.ini. Therefore, you need to connect via SSH with the command line interface of the CKAN Server. 3 First Steps This chapter describes the basic elements of CKAN. Using a step-by-step approach, specific test data will be generated. These test data are already established on your CKAN installation you can simply delete them, if not needed. For the first steps you need to log into the system. 3.1 Organizations and Users Each dataset that is published via CKAN belongs to an organization. Datasets can be edited by users, each user belongs to an organization. One or more users can be administrators for an organization. These organizational administrators can set up new users within their organizations and configure data and publishing parameters. Within CKAN, multiple organizations with organization-specific publishing guidelines can be set up. That way, public service structures and responsibilities can be modelled and administrated. Step one: Set Up an Organization First, log in as system administrator. Choose Organization hinzufügen ( Add Organization ) in the Area Organisationen ( Organizations ) and fill the form. OpenData-CKAN@Azure_Manual_en_v1.2.docx 5 / 12
Using Organisation erstellen ( Add Organization ) a new organization account will be created, stored in the data base and subsequently will be listed in the Organisationen ( Organizations ) overview. Step two: Editing Organisation s Settings and Adding Users Choose the newly created organization from the list on the organization page. You will see the organization page. Using the option Bearbeiten ( Edit ) you can edit general data and add new users. OpenData-CKAN@Azure_Manual_en_v1.2.docx 6 / 12
Within an organization, users can have three different roles: a) Administrator: set up, edit and delete datasets; administrate organization s users b) Editor: set up, edit and delete datasets c) User (Mitglied): can see datasets of his/her organization, cannot set up datasets Now, add a new user (Mitglied) with the role editor (Bearbeiter). All following steps will be performed with this newly added user. Important hint: The test user has he following access data for the sample data: Account (Benutzername): tester-1286 Password (Kennwort): abc1234 If you want to continue working with this Account, change the password immediately, otherwise delete the account before going public. 3.2 Groups In CKAN, groups are used to bundle and to categorize datasets, e.g. datasets belonging to a certain project or to a certain team. Groups and organizations resemble each other in appearance. The difference becomes visible, when it comes to access rights. OpenData-CKAN@Azure_Manual_en_v1.2.docx 7 / 12
Organizations can bundle and control users, who are creating, changing, publicly or privately (for internal use only) publishing datasets. That way, an editor or an administrator of an organization can create a new dataset. However, editors or administrators if a group can bundle or exclude datasets of their CKAN in their group. Thus, groups are used for data-consuming users, who are using, collecting or bundling theme-related data. In short words: users are creating data related to their organization, but rather using data related to their groups. Third Step: Creating and Editing Groups In principle, the method for creating a group is similar to the method for creating an organization. Choose Gruppen > Gruppe hinzufügen ( Groups -> Add group ) and add a new group. Two hints: Pictures can support intuitive understanding of datasets simply use this opportunity! Edit groups by choosing Bearbeiten ( Edit ) and add a picture. OpenData-CKAN@Azure_Manual_en_v1.2.docx 8 / 12
You also have the opportunity to use Benutzerdefinierte Felder ( User defined entries ) for adding information. In the example above information on the creation date was added. 3.3 Datasets CKAN is an Open-Data platform that means that the most important content is data or so called datasets. Each dataset will be registered separately. If you have two series of measurements for the ozone concentration in your city both for 2013 and 2014, just create two new datasets in your CKAN system. Before you start, some explanations regarding datasets. A CKAN dataset is a quantity of data resources - e.g. Excel data tables with ozone measurements and some accompanying information. This information contains: - A meaningful title - Key words (tags) - Licensing information (e.g. CCA, PDDL), - Organizational information - Visibility information (private, public), OpenData-CKAN@Azure_Manual_en_v1.2.docx 9 / 12
- Information on source, version, author etc. - Further individual information Another hint: By assigning editors to organizations and datasets to editors you will create a structure that shows not only data, but also data sources (organizations) and contact persons (editors). Fourth Step: Creating a Dataset Let s get practical. Choose Datensätze > Datensatz hinzufügen ( Datasets -> Add dataset ), create a new dataset and edit the accompanying information. After you have filled the mandatory fields, you choose the second step Daten hinzufügen ( Add data ). OpenData-CKAN@Azure_Manual_en_v1.2.docx 10 / 12
You can either upload your data directly onto the CKAN server (e.g. your Excel sheet with ozonee measurements) or alternatively set a link to a Web-service or to a REST-service. OpenData-CKAN@Azure_Manual_en_v1.2.docx 11 / 12
In our example, the Excel-sheet was uploaded directly and name as well as the data description were added. In addition it may be of help to document the data format in this particular case it is not needed because CKAN automatically recognizes Excel as data format. Another hint: As long as they belong to the respective content, you can add any number of resources to a dataset, be it additional files with xml, json or pdf format. But please avoid to add a table with ozone measurements of 2014 to the dataset of 2015. It is recommended to therefore open a separate dataset. 3.4 Searching for Data After you have added data to CKAN you now may want to search and recover them in CKAN. Therefore you can both use a search entry as well a structured search via search criteria like formats, keywords or licenses to recover your data. It is also possible to search data in data catalogues of organizations or groups. One of the biggest advantages is that CKAN provides an API (machine-to-machine interface) allowing data processing in other systems. 4 Conclusion The chapters above gave you a step-by-step approach to create data on your CKAN server and offer them to the public by effective search interfaces and functionality. This complete process beginning with establishing the CKAN-Image and the virtual machine in Microsoft Azure, including its basic configuration as well as the process of adding data took only a few minutes. We look forward to answer all your questions according to open data / CKAN just ask us: http://www.teleport.de OpenData-CKAN@Azure_Manual_en_v1.2.docx 12 / 12