################################################################# # # # BUGGER V1.0 # # Install Procedure # # # # Document Author: Ben Tasker # # Document Date: 10/12/2009 # # Filename: 20091210_BUGGER_Install_procedures.txt # # # ################################################################# Contents --------- - Warnings - License - Known Issues - Extract Components - Configure BUGGER - BUGGER Config - Projects - Install Database - Install Scripts - Install Web Components - Default Settings - Captchas - Password - Log in - Create new user - Bugs Warnings --------- Before you install BUGGER be sure you read this document carefully. Also be aware that BUGGER is still in the very early stages of development, and is provided as is with no warranty either express or implied (To the extent allowed by law). BUGGER shouldn't lose your data, but if it does, the author can accept no responsibility. This is currently classed as EXPERIMENTAL SOFTWARE and should be treated as such. License -------- BUGGER is copyright Ben Tasker 2009 and is released under the GNU GPL V3. See either the LICENSE file in the utils directory of the tarball, or http://benscomputer.no-ip.org/LICENSE3 for a copy of the license. Known Issues ------------- There are certain features missing, for example the Log Out function does not currently exist. To Log In as a different user you will need to access the Log In form directly and then log in as the new user. Authentication is currently a little weak. Whilst passwords are stored as salted hashes and SSL should be employed when sending passwords, there are currently a few ways a malicious user could gain admin access to BUGGER without providing a password. However, unless you have failed to reset the default password, these methods all require an Admin user to be logged in at the time of the attack. This issue has been listed as high priority for the next release. Extract Components -------------------- Extract the tarball with the following command. tar xvzf BUGGER_version.tar.gz This will present you with 4 directories; - Bugs - Projects - BUGGER - Utils Bugs contains the Database, this will need to be copied to the Claims_DB server and installed into the database. Projects contains the CGI files BUGGER contains the webcomponents Utils contains a copy of this file, the License and a couple of useful utilities Configure BUGGER ----------------- - BUGGER Config You are almost ready to begin installing BUGGER. First you need to configure BUGGER so that it knows where to find your Database Server. Open the file Projects/BUGGER_config.sh in a text editor nano Projects/BUGGER_config.sh Find the line reading output_config () This is the function that generates the config, within the EOM wrappers there are a number of variables. These are; DATABASE_SERVER="" WEBSERVER="" NONSSLWEBSERVER="" FQDN_SERVER="" UPLOAD_URL="" DBUSERNAME="" DBPASS="" DATABASE_SERVER defines the address to access the Claims_DB server on. This can be a DNS hostname or an I.P. Address. It's recommended that you configure the webserver running on the Claims_DB server to use SSL by default. WEBSERVER defines the Fully qualified domain name and the protocol to use for secure connections (password submission etc.) NONSSLWEBSERVER defines the fully qualified domain name and the protocol to use for non secure connections (most functions). If you want all connections secured you can use https instead of http in this variable to force secure connections. FQDN_SERVER defines the Fully qualified domain name of the server (no protocol included) UPLOAD_URL defines a URL that users can use to upload files to your webserver. Leave this blank if you don't want to offer users this function (it is restricted to Developers and above) DBUSERNAME defines the Username to use to authenticate with the Claims_DB_listener on your remote server. This is not currently fully supported, so can be ignored for the time being. DBPASS defines the password to use to authenticate with the Claims_DB_listener on your remote server. This is not currently fully supported, so can be ignored for the time being. Example: DATABASE_SERVER="MyDBserver.com" WEBSERVER="https://www.Mywebserver.com" NONSSLWEBSERVER="http://www.Mywebserver.com" FQDN_SERVER="Mywebserver.com" UPLOAD_URL="Mywebserver.com/Uploadform.html" DBUSERNAME="" DBPASS="" - Projects BUGGER currently lacks an interface to update project details. You will need to manually add these to the file Bugs/Projects.csv This is a CSV file utilising the following layout; "Project Ref","Project Name","Start Date","Development Stopped?", "Project Description","Maintainer" For example; "1","Claims_DB",17/05/09,"N","A CSV Based Database System","B Tasker" You should use a unique numerical value for Project Ref. This will allow BUGGER to autogenerate Primary keys for new projects when this functionality has been implemented. If you do not feel confident editing this file in a text editor, you can use a spreadsheet program (Comma Seperated file with double quotes as text delimiters) Install Database ----------------- Copy the Bugs directory to your Claims_DB server; scp -R User@MY_SERVER://path/to/claims_DB/db/dir Bugs Log onto the Database server and ensure that the tables are writeable by whichever user your Webserver runs as. For example: cd /path/to/claims_DB/db/dir/Bugs/ chown apache *.csv Install Scripts ---------------- Copy the Projects directory to the cgi-bin directory of your webserver (e.g. /var/wwwroot/cgi-bin/) cp -r Projects/ /var/wwwroot/cgi-bin/ Make the files executable for whichever user your webserver runs as chmod +x /var/wwwroot/cgi-bin/Projects/* Install Web Components ----------------------- Now we need to install the Web components, These are simple SHTML files containing an apache Server Side Include command. You may need to adjust the configuration of your webserver to recognise these if you are not running apache. Consult the relevant documentation for more information. Copy the BUGGER file to the root of your webserver cp -r BUGGER /var/wwwroot/htdocs/ Default Settings ----------------- Captchas ---------- There are currently 3 default captchas in the system. These are stored in the table Security. If you wish to change these, you currently need to edit the table directly (the functionality will be included at a later date.) You can do this either in a text editor, or a spreadsheet program (Comma Seperated with Double quotes for text delimiting) The default captchas are; Question | Answer ---------------------------------- 2 + 2 | 4 4 + 4 | 8 1 + 1 | 2 The Table is laid out in the following format; Page, Question, Answer, Enabled If you wish to turn a captcha off, set its enabled value to N. Passwords ----------- The system comes with two users preconfigured. The first is the system Administrator, the second is the user that the system uses to refresh cache files. The credentials you will need to log in for the first time are; User Name: Administrator Password: BUGGERuser1 Once you have logged in, change the password! You can also create yourself a new username once you have logged in. Log In ------- To access BUGGER enter the following web address into your web browser (Replace Yourwebserver.com with the web address of your webserver). http://Yourwebserver.com/BUGGER This will take you to the BUGGER main page. In the top right hand corner there is a link reading Log In. Click this link to access the Login form. Enter the username Administrator and the password BUGGERuser1 and press Log in. The system will authenticate you and welcome to the system, click the link reading Home to be taken back to the main page. Now that you are logged in a lot more options are available. Click the option in the top right hand corner of the page to change the Administrator password. Create New Username -------------------- To create your new user account, click the button labelled Create New User. This will take you to the user creation form enter a Username, a Display Name, and an E-mail address. Ensure Disabled is set to N and then assign yourself the privileges that you require. Hit Save to save the changes. The system will confirm whether this action was successful or not. Before you can use the account you will need to set a password. From the main menu, enter your new username into the username box and click Edit User. On the Bottom Left of the Edit user page is a button labelled Reset Users password. Click this to be taken to the password set form. Enter your new password twice. Click Change Password You can now use your new account by returning to the login page (change the URL in your address bar to /BUGGER/Login.shtml) Bugs ----- Issues with BUGGER can be reported at http://benscomputer.no-ip.org/BUGGER/ or alternatively you can use the Contact Form at http://benscomputer.no-ip.org/Contact.html (please only use this if you are unable to post the Bug to BUGGER.) ################################################################# # # # DOCUMENT END # # Copyright Ben Tasker 2009 # # Released under the GNU GPL V3 # # # #################################################################