diff --git a/doc/index.rst b/doc/index.rst index d5be74de521..a95855e0bac 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,6 +35,8 @@ advanced documentation last: .. toctree:: :maxdepth: 2 + user-guide + sysadmin-guide installing upgrading getting-started diff --git a/doc/sysadmin-guide.rst b/doc/sysadmin-guide.rst new file mode 100644 index 00000000000..fbf95ed51d5 --- /dev/null +++ b/doc/sysadmin-guide.rst @@ -0,0 +1,151 @@ +****************** +The Sysadmin Guide +****************** + +This guide covers the administration features of CKAN 2.0, such as managing +users and datasets. These features are available via the web user interface to +a user with sysadmin rights. The guide assumes familiarity with the +:doc:`user-guide`. + +Certain administration tasks are not available through the web UI but need +access to the server where CKAN is installed. These include the range of +configuration options using the site's "config" file, documented in +:doc:`configuration`, and those available via the :doc:`paster`. + +.. warning:: + +A sysadmin user can access and edit any Organizations, view and change user +details, and permanently delete datasets. You should carefully consider who has +access to a sysadmin account on your CKAN system. + +.. contents:: + +=========================== +Creating a sysadmin account +=========================== + +Normally, a sysadmin account is created as part of the process of setting up +CKAN. If one does not already exist, you will need to create a sysadmin user, +or give sysadmin rights to an existing user. To do this requires access to the +server; see :doc:`paster` for details. If another organization is hosting +CKAN, you will need to ask them to create a sysadmin user. + +Adding more sysadmin accounts is done in the same way. It cannot be done via +the web UI. + +========================= +Customizing look and feel +========================= + +Some simple customizations to customize the 'look and feel' of your CKAN site +are available via the UI, at ``http:///ckan-admin/config/``. + +.. image:: http://farm6.staticflickr.com/5487/9731703724_ddaaba24e4.jpg + +Here you can edit the following: + +Site title + This title is used in the HTML of pages served by CKAN (which may + be displayed on your browser's title bar). For example if your site title is + "CKAN Demo", the home page is called "Welcome - CKAN Demo". The site title is + also used in a few other places, e.g. in the alt-text of the main site logo. + +Style + Choose one of five colour schemes for the default theme. + +Site tag line + This is not used in CKAN's current default themes, but may be used in + future. + +Site tag logo + A URL for the site logo, used at the head of every page of CKAN. + +About + Text that appears on the "about" page, ``http://<my-ckan-url>/about``. You + can use `Markdown`_ here. If it is left empty, a standard text describing CKAN + will appear. + +.. _Markdown: http://daringfireball.net/projects/markdown/basics + +Intro text + This text appears prominently on the home page of your site. + +Custom CSS + For simple style changes, you can add CSS code here which will be added to + the ``<head>`` of every page. + +=================================== +Managing Organizations and datasets +=================================== + +A sysadmin user has full access to user accounts, organizations and datasets. +For example, you have access to every Organization as if you were a member of +that Organization. Thus most management operations are done in exactly the same +way as in the normal web interface. + +For example, to add or delete users to an Organization, change a user's role in +the Organization, delete the Organization or edit its description, etc, visit +the Organization's home page. You will see the 'Admin' button as if you were a +member of the Organization. You can use this to perform all Organization admin +functions. For details, see the :doc:`user-guide`. + +Similarly, to edit, update or delete a dataset, go to the dataset page and use +the 'Edit' button. As an admin user you can see all datasets including those +that are private to an Organization. They will show up when doing a dataset +search. + +-------------------------------------- +Moving a dataset between Organizations +-------------------------------------- + +To move a dataset between Organizations, visit the dataset's Edit page. Choose +the appropriate entry from the "Organization" drop-down list, and press "Save". + +.. image:: http://farm8.staticflickr.com/7341/9731703624_bdf1712191.jpg + +============================= +Permanently deleting datasets +============================= + +A dataset which has been deleted is not permanently removed from CKAN; it is +simply marked as 'deleted' and will no longer show up in search, etc. The +dataset's URL cannot be re-used for a new dataset. + +To permanently delete ("purge") a dataset: + +* Navigate to the dataset's "Edit" page, and delete it. +* Visit ``http://<my-ckan-url>/ckan-admin/trash/``. + +This page shows all deleted datasets and allows you to delete them permanently. + +.. warning:: + + This operation cannot be reversed! + +.. note:: + + At present, it is not possible to purge Organizations or groups using the + web UI. This can only be done with access to the server, by directly deleting + them from CKAN's database. + +============== +Managing users +============== + +To find a user's profile, go to ``http://<my-ckan-url>/user/``. You can search +for users in the search box provided. + +You can search by any part of the user profile, including their e-mail address. +This is useful if, for example, a user has forgotten their user ID. For +non-sysadmin users, the search on this page will only match public parts of the +profile, so they cannot search by e-mail address. + +On their user profile, you will see an "Edit" button. CKAN displays the user +settings page. You can change any settings for the user, including their +username, name and password. + +.. image:: http://farm3.staticflickr.com/2859/9728870203_764d22fbda.jpg + +.. note:: + + At present, it is not possible to delete users. diff --git a/doc/user-guide.rst b/doc/user-guide.rst new file mode 100644 index 00000000000..233089a003e --- /dev/null +++ b/doc/user-guide.rst @@ -0,0 +1,526 @@ +************** +The User Guide +************** + +This user guide covers using CKAN's web interface to organize, publish and find +data. CKAN also has a powerful API (machine interface), which makes it easy to +develop extensions and links with other information systems. The API is +documented in :doc:`api`. + +Some web UI features relating to site administration are available only to +users with sysadmin status, and are documented in :doc:`sysadmin-guide`. + +============= +What is CKAN? +============= + +CKAN is a tool for making open data websites. (Think of a content management +system like WordPress - but for data, instead of pages and blog posts.) It +helps you manage and publish collections of data. It is used by national and +local governments, research institutions, and other organizations who collect a +lot of data. + +Once your data is published, users can use its faceted search features to +browse and find the data they need, and preview it using maps, graphs and +tables - whether they are developers, journalists, researchers, NGOs, citizens, +or even your own staff. + +---------------------- +Datasets and resources +---------------------- + +For CKAN purposes, data is published in units called "datasets". A dataset is a +parcel of data - for example, it could be the crime statistics for a region, +the spending figures for a government department, or temperature readings from +various weather stations. When users search for data, the search results they +see will be individual datasets. + +A dataset contains two things: + +* Information or "metadata" about the data. For example, the title and + publisher, date, what formats it is available in, what licence it is released + under, etc. + +* A number of "resources", which hold the data itself. CKAN does not mind what + format the data is in. A resource can be a CSV or Excel spreadsheet, XML file, + PDF document, image file, linked data in RDF format, etc. CKAN can store the + resource internally, or store it simply as a link, the resource itself being + elsewhere on the web. A dataset can contain any number of resources. For + example, different resources might contain the data for different years, or + they might contain the same data in different formats. + +-------------------------------------- +Users, Organizations and authorization +-------------------------------------- + +CKAN users can register user accounts and log in. Normally (depending on the +site setup), login is not needed to search for and find data, but is needed for +all publishing functions: datasets can be created, edited, etc by users with +the appropriate permissions. + +Normally, each dataset is owned by an "Organization". A CKAN instance can have +any number of Organizations. For example, if CKAN is being used as a data +portal by a national government, the Organizations might be different +government departments, each of which publishes data. Each Organization can +have its own workflow and authorizations, allowing it to manage its own +publishing process. + +An Organization's administrators can add add individual users to it, with +different roles depending on the level of authorization needed. A user in an +Organization can create a dataset owned by that Organization. In the default +setup, this dataset is initially private, and visible only to other users in +the same Organization. When it is ready for publication, it can be published at +the press of a button. This may require a higher authorization level within the +Organization. + +Datasets cannot normally be created except within Organizations. It is +possible, however, to set up CKAN to allow datasets not owned by any +Organization. Such datasets can be edited by any logged-in user, creating the +possibility of a wiki-like datahub. + +.. note:: + + The user guide covers all the main features of the web user interface (UI). + In practice, depending on how the site is configured, some of these functions + may be slightly different or unavailable. For example, in an official CKAN + instance in a production setting, the site administrator will probably have + made it impossible for users to create new Organizations via the UI. You can + try out all the features described at http://demo.ckan.org. + +========== +Using CKAN +========== + +-------------------------- +Registering and logging in +-------------------------- + +.. note:: + + Registration is needed for most publishing features and for personalization + features, such as "following" datasets. It is not needed to search for and + download data. + +To create a user ID, use the "Register" link at the top of any page. CKAN will +ask for the following: + +* *Username* -- choose a username using only letters, numbers, - and _ characters. + For example, "jbloggs" or "joe_bloggs93". + +* *Full name* -- to be displayed on your user profile + +* *E-mail address* -- this will not be visible to other users + +* *Password* -- enter the same password in both boxes + +.. image:: http://farm4.staticflickr.com/3680/9096223468_a8fde8de23_z.jpg + +If there are problems with any of the fields, CKAN will tell you the problem +and enable you to correct it. When the fields are filled in correctly, CKAN +will create your user account and automatically log you in. + +.. note:: + + It is perfectly possible to have more than one user account attached to the + same e-mail address. For this reason, choose a username you will remember, as + you will need it when logging in. + +----------------------- +Features for publishers +----------------------- + +.. _adding_a_new_dataset: + +Adding a new dataset +==================== + +.. note:: + + You may need to be a member of an Organization in order to add and edit + datsets. See the section :ref:`creating_an_organization` below. On + http://demo.ckan.org, you can add a dataset without being in an Organization, + but dataset features relating to authorization and Organizations will not be + available. + +**Step 1**. You can access CKAN's "Create dataset" screen in two ways. + + a) Select the "Datasets" link at the top of any page. From this, above the + search box, select the "Add Dataset" button. + + b) Alternatively, select the "Organizations" link at the top of a page. Now + select the page for the Organization that should own your new dataset. Provided + that you are a member of this Organization, you can now select the "Add + Dataset" button above the search box. + +**Step 2**. CKAN will ask for the following information about your data. (The +actual data will be added in step 4.) + + * *Title* -- this title will be unique across CKAN, so make it brief but specific. + E.g. "UK population density by region" is better than "Population figures". + + * *Description* -- You can add a longer description of the dataset here, including + information such as where the data is from and any information that people will + need to know when using the data. + + * *Tags* -- here you may add tags that will help people find the data and link it + with other related data. Examples could be "population", "crime", "East + Anglia". Hit the <return> key between tags. If you enter a tag wrongly, you can + use its delete button to remove it before saving the dataset. + + * *License* -- it is important to include licence information so that people know + how they can use the data. This field should be a drop-down box. If you need to + use a licence not on the list, contact your site administrator. + + * *Organization* - If you are a member of any Organizations, this drop-down will + enable you to choose which one should own the dataset. Ensure the default + chosen is the correct one before you proceed. (Probably most users will be in + only one Organization. If this is you, CKAN will have chosen your Organization + by default and you need not do anything.) + +.. image:: http://farm4.staticflickr.com/3785/9093997647_afd26f6c50_z.jpg + +.. note:: + + By default, the only required field on this page is the title. However, it + is good practice to include, at the minimum, a short description and, if + possible, the licence information. You should ensure that you choose the + correct Organization for the dataset, since at present, this cannot be changed + later. You can edit or add to the other fields later. + +**Step 3**. When you have filled in the information on this page, select the "Next: Add +Data" button. (Alternatively select "Cancel" to discard the information filled +in.) + +**Step 4**. CKAN will display the "Add data" screen. + +.. image:: http://farm4.staticflickr.com/3716/9096225054_0759a4233e_z.jpg + +This is where you will add one or more "resources" which contain the data for +this dataset. Choose a file or link for your data resource and select the +appropriate choice at the top of the screen: + + * If you are giving CKAN a link to the data, like + ``http://example.com/mydata.csv``, then select "Link to a file" or "Link to an + API". (If you don't know what an API is, you don't need to worry about this + option - select "Link to a file".) + + * If the data to be added to CKAN is in a file on your computer, select "Upload + a file". CKAN will give you a file browser to select it. + +**Step 5**. Add the other information on the page. CKAN does not require this +information, but it is good practice to add it: + + * *Name* -- a name for this resource, e.g. "Population density 2011, CSV". + Different resources in the dataset should have different names. + + * *Description* -- a short description of the resource. + + * *Format* -- the file format of the resource, e.g. CSV (comma-separated + values), XLS, JSON, PDF, etc. + +**Step 6**. If you have more resources (files or links) to add to the dataset, select +the "Save & add another" button. When you have finished adding resources, +select "Next: Additional Info". + +**Step 7**. CKAN displays the "Additional data" screen. + + * *Visibility* -- a ``Public`` dataset is public and can be seen by any user of the + site. A ``Private`` dataset can only be seen by members of the Organization owning + the dataset and will not show up in searches by other users. + + * *Author* -- The name of the person or organization responsible for producing + the data. + + * *Author e-mail* -- an e-mail address for the author, to which queries about + the data should be sent. + + * *Maintainer / maintainer e-mail* -- If necessary, details for a second person + responsible for the data. + + * *Custom fields* -- If you want the dataset to have another field, you can add + the field name and value here. E.g. "Year of publication". Note that if there + is an extra field that is needed for a large number of datasets, you should + talk to your site administrator about changing the default schema and dataset + forms. + + * *Group* -- Moderated collection of datasets. You can add the dataset to + an existing group here. + +.. image:: http://farm6.staticflickr.com/5349/9093997235_910e725a52_z.jpg + +.. note:: + + Everything on this screen is optional, but you should ensure the + "Visibility" is set correctly. It is also good practice to ensure an Author is + named. + +**Step 8**. Select the 'Finish' button. CKAN creates the dataset and shows you +the result. You have finished! + +You should be able to find your dataset by typing the title, or some relevant +words from the description, into the search box on any page in your CKAN +instance. For more information about finding data, see the section +:ref:`finding_data`. + + +Editing a dataset +================= + +You can edit the dataset you have created, or any dataset owned by an +Organization that you are a member of. (If a dataset is not owned by any +Organization, then any registered user can edit it.) + +#. Go to the dataset's page. You can find it by entering the title in the search box on any page. + +#. Select the "Edit" button, which you should see above the dataset title. + +#. CKAN displays the "Edit dataset" screen. You can edit any of the fields + (Title, Description, Dataset, etc), change the visibility (Private/Public), and + add or delete tags or custom fields. For details of these fields, see + :ref:`adding_a_new_dataset`. + +#. When you have finished, select the "Update dataset" button to save your changes. + +.. image:: http://farm4.staticflickr.com/3773/9093996355_35ce6b2495_z.jpg + + +Adding, deleting and editing resources +====================================== + +#. Go to the dataset's "Edit dataset" page (steps 1-2 above). + +#. In the left sidebar, there are options for editing resources. You can select + an existing resource (to edit or delete it), or select "Add new resource". + +#. You can edit the information about the resource or change the linked or + uploaded file. For details, see steps 4-5 of "Adding a new resource", above. + +#. When you have finished editing, select the button marked "Update resource" + (or "Add", for a new resource) to save your changes. Alternatively, to delete + the resource, select the "Delete resource" button. + + +Deleting a dataset +================== + +#. Go to the dataset's "Edit dataset" page (see "Editing a dataset", above). + +#. Select the "Delete" button. + +#. CKAN displays a confirmation dialog box. To complete deletion of the + dataset, select "Confirm". + +.. note:: + + The "Deleted" dataset is not completely deleted. It is hidden, so it does + not show up in any searches, etc. However, by visiting the URL for the + dataset's page, it can still be seen (by users with appropriate authorization), + and "undeleted" if necessary. If it is important to completely delete the + dataset, contact your site administrator. + + +.. _creating_an_organization: + +Creating an Organization +======================== + +In general, each dataset is owned by one Organization. Each Organization +includes certain users, who can modify its datasets and create new ones. +Different levels of access privileges within an Organization can be given to +users, e.g. some users might be able to edit datasets but not create new ones, +or to create datasets but not publish them. Each Organization has a home page, +where users can find some information about the Organization and search within +its datasets. This allows different data publishing departments, bodies, etc to +control their own publishing policies. + +To create an organization: + +#. Select the "Organizations" link at the top of any page. + +#. Select the "Add Organization" button below the search box. + +#. CKAN displays the "Create an Organization" page. + +#. Enter a name for the Organization, and, optionally, a description and image + URL for the Organization's home page. + +#. Select the "Create Organization" button. CKAN creates your Organization and + displays its home page. Initially, of course, the Organization has no datasets. + +.. image:: http://farm6.staticflickr.com/5338/9093996867_d4640f158d_z.jpg + +You can now change the access privileges to the organization for other users - +see :ref:`managing_an_organization` below. You can also create datasets owned by the +Organization; see :ref:`adding_a_new_dataset` above. + +.. note:: + + Depending on how CKAN is set up, you may not be authorized to create new + Organizations. In this case, if you need a new Organization, you will need to + contact your site administrator. + + +.. _managing_an_organization: + +Managing an Organization +======================== + +When you create an Organization, CKAN automatically makes you an "Admin" of the +Organization. From the Organization's page you should see an "Admin" button +above the search box. When you select this, CKAN displays the Organization +admin page. This page has two tabs: + +* *Info* -- Here you can edit the information supplied when the Organization + was created (title, description and image). + +* *Members* -- Here you can add, remove and change access roles for different + users in the Organization. Note: you will need to know their username on CKAN. + +.. image:: http://farm4.staticflickr.com/3792/9093996089_372c44d739_z.jpg + +By default CKAN allows members of Organizations with three roles: + +* *Member* -- can see the Organization's private datasets + +* *Editor* -- can edit and publish datasets + +* *Admin* -- can add, remove and change roles for Organization members + +.. _finding_data: + +------------ +Finding data +------------ + +Searching the site +================== + +To find datasets in CKAN, type any combination of search words (e.g. "health", +"transport", etc) in the search box on any page. CKAN displays the first page +of results for your search. You can: + +* View more pages of results + +* Repeat the search, altering some terms + +* Restrict the search to datasets with particular tags, data formats, etc using + the filters in the left-hand column + +If there are a large number of results, the filters can be very helpful, since +you can combine filters, selectively adding and removing them, and modify and +repeat the search with existing filters still in place. + +If datasets are tagged by geographical area, it is also possible to run CKAN +with an extension which allows searching and filtering of datasets by selecting +an area on a map. + +.. image:: http://farm3.staticflickr.com/2827/9093995825_ae5ff329c8_z.jpg + + +Searching within an Organization +================================ + +If you want to look for data owned by a particular Organization, you can search +within that Organization from its home page in CKAN. + +#. Select the "Organizations" link at the top of any page. + +#. Select the Organization you are interested in. CKAN will display your + Organization's home page. + +#. Type your search query in the main search box on the page. + +CKAN will return search results as normal, but restricted to datasets from the +Organization. + +If the Organization is of interest, you can opt to be notified of changes to it +(such as new datasets and modifications to datasets) by using the "Follow" +button on the Organization page. See the section :ref:`managing_your_news_feed` +below. You must have a user account and be logged in to use this feature. + + +Exploring datasets +================== + +When you have found a dataset you are interested and selected it, CKAN will +display the dataset page. This includes + +* The name, description, and other information about the dataset + +* Links to and brief descriptions of each of the resources + +.. image:: http://farm3.staticflickr.com/2831/9096224166_5794daefc5_z.jpg + +The resource descriptions link to a dedicated page for each resource. This +resource page includes information about the resource, and enables it to be +downloaded. Many types of resource can also be previewed directly on the +resource page. .CSV and .XLS spreadsheets are previewed in a grid view, with +map and graph views also available if the data is suitable. The resource page +will also preview resources if they are common image types, PDF, or HTML. + +The dataset page also has two other tabs: + +* *Activity stream* -- see the history of recent changes to the dataset + +* *Related items* -- see any links to web pages related to this dataset, or add + your own links. + +If the dataset is of interest, you can opt to be notified of changes to it by +using the "Follow" button on the dataset page. See the section +:ref:`managing_your_news_feed` below. You must have a user account and be +logged in to use this feature. + +--------------- +Personalization +--------------- + +CKAN provides features to personalize the experience of both searching for and +publishing data. You must be logged in to use these features. + +.. _managing_your_news_feed: + +Managing your news feed +======================= + +At the top of any page, select the dashboard symbol (next to your name). CKAN +displays your News feed. This shows changes to datasets that you follow, and +any changed or new datasets in Organizations that you follow. The number by the +dashboard symbol shows the number of new notifications in your News feed since +you last looked at it. As well as datasets and Organizations, it is possible to +follow individual users (to be notified of changes that they make to datasets). + +.. image:: http://farm4.staticflickr.com/3810/9093996225_461182be69_z.jpg + +If you want to stop following a dataset (or Organization or user), go to the +dataset's page (e.g. by selecting a link to it in your News feed) and select +the "Unfollow" button. + +Managing your user profile +========================== + +You can change the information that CKAN holds about you, including what other +users see about you by editing your user profile. (Users are most likely to see +your profile when you edit a dataset or upload data to an Organization that +they are following.) To do this, select the gearwheel symbol at the top of any +page. + +.. image:: http://farm4.staticflickr.com/3819/9093995675_7e75eacfc5_z.jpg + +CKAN displays the user settings page. Here you can change: + +* Your username + +* Your full name + +* Your e-mail address (note: this is not displayed to other users) + +* Your profile text - an optional short paragraph about yourself + +* Your password + +Make the changes you require and then select the "Update Profile" button. + +.. note:: + + If you change your username, CKAN will log you out. You will need to log + back in using your new username.