%META:TOPICINFO{author="KingsleyIdehen" date="1166215353" format="1.1" version="1.1"}% %META:TOPICPARENT{name="Ods"}% %VOSNAV% %TOC% ---++OpenLink Data Spaces (ODS) Quick Start ---+++ Configuring ODS ODS is now delivered as part of the Virtuoso Open Source 5.0 edition. This page provides instructions on installation of the ODS suite of Data Space applications. Please note that ODS is preinstalled into the Virtuoso Demo Database. Thus, you do not need to perform the installation steps below if working with a Virtuoso 5.0 (or higher) demonstration database. ---++++ Configuration Parameters ODS depends on certain parameters in the Virtuoso Database Initialization File (INI file) e.g. "demo.ini" for the demonstration database. The settings in this file are appropriate for most installations. Thus, prior to starting the Virtuoso server you need to verify that the following parameters in the INI file are set: * HTTP Server is enabled ('HTTPServer' section) * The default mail server is properly specified in DefaultMailServer INIoption of the 'HTTPServer' section. This must point to a valid SMTP server for outgoing mail. * The URIQA section must have a proper 'DefaultHost' setting, and must contain the name and http port of the HTTP listener. This name must be valid across the network where ODS will be used. This may require you to have a CNAME or similar entry in DNS for the service. For example: [URIQA] DefaultHost = demo.mydomain.com:1112 See the [[http://docs.openlinksw.com/virtuoso/dbadm.html#ini_URIQA][URIQA section]] in the documentation for more details. * The ImageMagick, Wikiv, CreoleWiki, MediaWiki plugins are enabled via the following entries in the "[Plugins]" section: [Plugins] ... other plugins.. LoadPath = /usr/local/lib Load1 = plain,im Load2 = plain,wikiv Load3 = plain,mediawiki Load5 = plain,creolewiki ... other plugins ... ---+++Locate and install the VAD packages ---++++VAD Packages Once you have verified the server settings, the next step is to install the VAD packages. For binary distributions and the tree made by make install, they are located in the share/virtuoso/vad directory under the installation root. If you are using the demo database, the packages are preinstalled. The ODS VAD packages for this release include: 1 [[OdsFramework][OpenLink Data Space (ODS) Framework]] ([[http://virtuoso.openlinksw.com/vads/ods_framework_dav.vad][ods_framework_dav.vad]]) 1 [[OdsBlog][ODS-WebBlog]] ([[http://virtuoso.openlinksw.com/vads/ods_blog_dav.vad][ods_blog_dav.vad]]) 1 [[OdsBriefcase][ODS-Briefcase]] ([[http://virtuoso.openlinksw.com/vads/ods_briefcase_dav.vad][ods_briefcase_dav.vad]]) 1 [[OdsFeedManager][ODS-Feed Manager]] ([[http://virtuoso.openlinksw.com/vads/ods_feedmanager_dav.vad][ods_feedmanager_dav.vad]]) 1 [[OdsWiki][ODS-Wiki]] ([[http://virtuoso.openlinksw.com/vads/ods_wiki_dav.vad][ods_wiki_dav.vad]]) 1 [[OdsMail][ODS-Mail]] ([[http://virtuoso.openlinksw.com/vads/ods_webmail_dav.vad][ods_webmail_dav.vad]]) 1 [[OdsBookmarkManager][ODS-Bookmark Manager]] ([[http://virtuoso.openlinksw.com/vads/ods_bookmark_dav.vad][ods_bookmark_dav.vad]]) 1 [[OdsGallery][ ODS-Gallery]] ([[http://virtuoso.openlinksw.com/vads/ods_gallery_dav.vad][ods_gallery_dav.vad]]) 1 [[OdsCommunity][ ODS-Community]] ([[http://virtuoso.openlinksw.com/vads/ods_community_dav.vad][ods_community_dav.vad]]) 1 [[OdsPolls][ ODS-Polls]] ([[http://virtuoso.openlinksw.com/vads/ods_polls_dav.vad][ods_polls_dav.vad]]) 1 [[OdsAddressbook][ ODS-Addressbook]] ([[http://virtuoso.openlinksw.com/vads/ods_addressbook_dav.vad][ods_addressbook_dav.vad]]) 1 [[OdsDiscussions][ ODS-Discussions]] ([[http://virtuoso.openlinksw.com/vads/ods_discussions_dav.vad][ods_discussions_dav.vad]]) ---+++++VAD Installation The next step is to install the VAD packages. With isql, run the following command: SQL> VAD_INSTALL('',0); Install the files in the order of the above listing. The web pages of the packages will go into the server's WebDAV repository. ---+++ DNS Settings If you wish to offer virtual host names for applications, as in myblog.example.com, then the DNS has to be set up to direct *.example.com to the host where Virtuoso is running. If users will not choose virtual host names for their applications, this step can be skipped. ---+++ Configure ODS The larger part of configuration is performed through the browser: * Enter the URL http://[host]:[port]/ods where the host and port are the server and port your Virtuoso instance is running on. (e.g. http://localhost:8890/ods/) * Login as "dav", the default password is "dav". * Click on "Site Settings" * Open the "Web Application Configuration" page and enter a Google API key. You can obtain a key by from http://www.google.com/apis/maps/signup.html, and choosing the appropriate Geocoder service. _Note that not all Geocoder services return addresses for non-US countries._ * Save the changes and return to the "Site Settings" via the link at the top. _You can skip these steps but then the map-related features will be disabled._ * Open the "Mail" settings page. * Specify the proper default mail domain, whether to use the default mail server (from the INI) or enter another. * Specify the proper ODS admin mail address and save the settings. * Press the "Test" button to verify that the mail settings actually work * Return to the "Site Settings" page * Enter the "Member Registration Settings" page * Select the desired registration scheme from the options, or if you are not sure what to use, just leave as it is. Here are the options that change the behavior of the ODS site registration: * "Allow WA Default-Site Registrations": if the registration is not allowed only users created by site admin will be able to login. * "Verify registration by email" - whether to send a mail to the new users with confirmation or create the account immediately. ODS is now ready for use. Note: if you disable the default site registration, then in addition to the above the ODS admin will need to create user accounts for the site members. ---+++ Configuring the ODS domain(s) In order to allow ODS users to create their own sub-domains (e.g. user.sample.domain, where ODS domain is sample.domain) the ODS should be configured via Conductor UI. The following describes how to enable an ODS domain : * Go to http://host:port/conductor * Login as 'dba' and open "WebDAV & HTTP" then "HTTP Hosts & Directories" * Specify the interface address, port to listen and domain like '0.0.0.0' (all interfaces), 8888 and 'sample.domain'in the form below the list and click 'Add' * Open "System Admin" then "Packages", open the Configure page for "Framework" package * Select "Create New Endpoint" link; the new ODS endpoint form should be shown * You can specify either "Endpoint prefix" or "Virtual directory" or both to enable the domain from selection list to be used as ODS domain. * Leave the "Domain registration" option enabled * Confirm the changes; the new ODS endpoint will be listed. After performing the above steps, when creating a new application instance, the new domain will be selectable when choosing a virtual host name for the application. ---+++ Customization * ODS pages The ODS pages can be modified by editing the *.vspx and *.css files in <Virtuoso OpenSource>/appsrc/ODS-Framework/ and then re-build the ods_dav.vad and re-install it. Alternately, you can install the ods_filesystem.vad package which will put the dynamic web pages in the filesystem and you can edit them as the server is running, as you would edit any dynamic web pages under PHP or similar. * User's home The users in ODS may wish to change the look and feel of their own home pages in the ODS. To do so, the user should go in 'Settings' page and enter the 'Home Page Template Selection'. In the presented text area he/she can edit the home page without any special permissions by ODS administrator. Note: The current ODS version of the ODS contains one 'default' home page template, which can serve as a basis for customization. ---+++ Adding users with Conductor IMPORTANT: Below are instructions for adding new user accounts if registrations are disabled. This can be performed in the Conductor (pre-installed on the Demo Database): * Open Conductor via browser at http://host:port/conductor (e.g. http://localhost:8890/conductor/) * login as 'dba' * go to "System Admin" and the "User Accounts" tab. * open the "Create New Account" page * enter the requested information and check "Allow DAV Logins". * repeat the previous step for every member of ODS * From the Conductor's left-hand menu click on the "Data Space" or "Web * Applications" link in the Conductor to commence using your Data Space applications. (This will take you to http://localhost:8890/ods/ .) ---+++ Configuring the Virtuoso mail handler Virtuoso provides a local mail delivery program (virt_mail) for SMTP servers. This program is used to store the received mail into the Virtuoso database. The following instructions are applicable to UNIX systems using sendmail as a mail server. ---++++ Virtuoso Mail Handler Configuration 1. Copy virt_mail to /usr/bin/virt_mail 2. Copy /binsrc/maildrop/odbc_mail.default.ini to /etc/odbc_mail.ini 3. Edit /etc/odbc_mail.ini and change the login settings to match your current database installation: [Options] DSN = DSN=Virtuoso; HOST=localhost:1111;UID=dba;PWD=dba ;MaxMessageSize = 2097152 Verify = DB.DBA.WA_MAIL_VALIDATE ('$local') Deliver = DB.DBA.WA_NEW_MAIL('$1', $message) (You can probably leave the rest of the odbc_mail.ini alone.) Note that DSN contains reference to the VOS server SQL port, so this should be replaced if non-default SQL port (1111) is used. ---++++ Sendmail program configuration Replace the default local mailer in your sendmail.cf ... #Mlocal, P=/usr/bin/procmail, F=lsDFMAw5:/|@qSPfhn9, S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, # T=DNS/RFC822/X-Unix, # A=procmail -t -Y -a $h -d $u Mlocal, P=/usr/bin/virt_mail, F=lsDFMA5:/|@qSPhn9, S=10/30, R=20/40, T=DNS/RFC822/X-Unix, A=virt_mail -c /etc/odbc_mail.ini -l $u -h $h -s $g ... IMPORTANT: make sure that ODS packages are installed prior to making the changes above. ---++++ Verify Mail Settings Send an e-mail to the 'dav' user account: bash$ mail dav@ Subject: virt-mail-test . Cc: Using the ISQL tool check the mailbox of the 'dav' user account: SQL> select mm_subj from mail_message where mm_own = 'dav'; MM_SUBJ VARCHAR _______________________________________________________________________________ virt-mail-test If you see the subject of the mail which was sent in previous step, then the handler works correctly. Otherwise you should check the log of the sendmail program. ---++++ Other SMTP Servers For the other mail server programs please consult INSTALL document in the <Virtuoso Open Source>/binsrc/maildrop/ directory. ---+++ Setting the VOS SMTP Mail handler on Win32 platforms Before to start you make sure that STMP services for Internet Information Services (IIS) are installed on your windows box. To check that open Control Panel, Add or Remove Programs, Add/Remove Windows Components. In the "Internet Information Services" see Details there you must have "SMTP Service" installed, if not check and proceed with windows installation update. Please note that windows installation disk may be asked. If SMTP Service is installed then proceed with following steps: * Open IIS configuration via Control Panel, Administrative Tools * Check the default SMTP Virtual server is running , and if needed add alias or domain. Note the domain name, this will be used in the next steps * Open a command prompt (CMD) * Go to the VOS binary distribution (c:\vos for example), in the c:\vos\bin directory * Make sure register.bat, smtpreg.vbs and virt_mail.ini are in place, if not download the ZIP (attached) and unpack in this directory * Run register.bat /register "domain-name" where the domain-name is domain that you wish to be served for the purpose (the one from second step) * If no error, you should see message like assigning priority (0 of 32767) registered OpenLink MailDrop set priority Command to c:\vos\bin\virt_mail.exe * Edit the c:\vos\bin\virt_mail.ini and edit HOST address and port to match your Virtuoso OpenSource server in following line : DSN = DSN=Virtuoso; HOST=localhost:1112;UID=dba;PWD=dba * Make sure Virtuoso OpenSource server is running and test the SMTP handler installation as follows: * Connect with ISQL tool to the VOS database and execute following commands: SQL> smtp_send ('localhost:25', 'dba@testdomain', 'dba@testdomain', 'Subject: test\r\n\r\ntest'); Done. -- 26 msec. SQL> select MM_SUBJ from mail_message; MM_SUBJ VARCHAR _______________________________________________________________________________ test 1 Rows. -- 0 msec. SQL> You should see a row with text "test" in the result. Please note that "testdomain" should be replaced by your domain (see above). * If something is broken, you can turn on logging in virt-mail.ini with uncommenting MailDebug setting * If all is ok, then change the Verify and Deliver options in virt_mail.ini to Verify = DB.DBA.WA_MAIL_VALIDATE ('$local') Deliver = DB.DBA.WA_NEW_MAIL('$1', $message) * The STMP mail handler is ready for use with VOS ODS applications %VOSCOPY%