########################################################################

#
# Project: Appupdater
# URL: http://www.nabber.org/projects/
# E-mail: webmaster@nabber.org
#
# Copyright: (C) 2007-2013, Neil McNab
# License: GNU General Public License Version 2
# (http://www.gnu.org/copyleft/gpl.html)
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# Filename: $URL: file:///nfs/sf-svn/a/ap/appupdater/code/releases/appupdater-
2.1/README.txt $
# Last Updated: $Date: 2013-12-31 00:37:32 +0000 (Tue, 31 Dec 2013) $
# Author(s): Neil McNab
#
# Description:
# This file contains overview information on the project.
#
########################################################################

VERSION: 2.1

1. INTRODUCTION
2. INSTALLATION
2.1. Windows Installer
2.2. Python Installer
2.3. Portable (USB Drive) Installation
3. TYPICAL USAGE
3.1. Command line
3.2. Running from Source
3.3. Graphical User Interface (GUI)
4. COMPLETE DOCUMENTATION
4.1. Command line
4.2. Windows Service
4.3. Portable (USB Drive)
4.4. Graphical User Interface (GUI)
5. ENTERPRISE DEPLOYMENT
6. CREATING YOUR OWN REPOSITORY
6.1. Requirements
6.2. Tools
7. PERMISSIONS
8. KNOWN ISSUES

1. INTRODUCTION
===============
Appupdater provides advanced functionality to Windows, similar to apt-get or
yum on Linux. It automates the process of installing and maintaining up to
date versions of programs. Fully customizable for use in a corporate
environment.

2. INSTALLATION
===============
2.1. Windows Installer
----------------------
You can either run the Windows installer program or see the next section on
the Python Installer. The Windows installer requires administrator
privileges and can be run silently by using the /S option.

2.2. Python Installer

---------------------
You need to install Python first. This should work on any OS.

python setup.py install

2.3. Portable (USB Drive) Installation

--------------------------------------
There are three ways that this can be done.

1. The recommended way to do this is to install directly to the USB device.

You should select the "Portable" install mode to minimize unneeded changes to
your Windows installation. This also copies GPG files to the portable
device, unlike the other methods described here.

2. Download the file that ends in -win32.zip. This contains all of the
program .exes that you need, you can unzip to any directory and it will work.

3. Simply install normally to your hard drive as described in part 2.1. Then
copy the installation folder (default C:\Program Files\Appupdater) to your
USB device.

3. TYPICAL USAGE
================
3.1. Command line
-----------------
You should run this application as root/administrator. Many installers require
root/administrator privileges and will not install without them.

Use this just like apt-get for Linux, a single command will update your system:

appupdater --update --upgrade

To install a specific application:

appupdater --install "packagename"

To list available packages:

appupdater --available

To list installed packages:

appupdater --list

When running into issues, you should always try running the --update option
first. This should fix most problems.

3.2. Running from Source

------------------------
You need to install Python first. Unzip the package files and then run the
program:

python appupdater.py (command line)

python appupdaterw.py (GUI)

3.3. Graphical User Interface (GUI)

-----------------------------------
Appupdater now ships with a GUI, you can run it by typing the following:

appupdaterw

You will be prompted to select a repository during the first run if one was
not selected during installation. Simply click the buttons in order to
update your system:

1. Download Apps List

2. Rescan
3. Download All Updates
4. Install All Updates

After completing this process you might still have applications shown in red
indicating that they still need to be updated. These applications likely
require you to install the updates manually by clicking through the
installation wizard. You can do this by clicking on the line number for the
application and then choosing "Install Manually..." and following the on
screen instructions.

4. COMPLETE DOCUMENTATION
=========================
4.1. Command line
-----------------
Each time you run the program you must choose a primary command. This will
break out each command and its options.

appupdater --update [--force] [--quick] [-y] [-d] [--cve]

Retrieves new lists of packages and scans the filesystem for them. This will
typically take the longest to run. Using the --force option will force a
complete download of the files, even if the cached version is still good.
The --force option should NEVER be used in a script. The --quick option
performs a quick search for installed programs. This search is not as
thorough, but generally completes in much less time. The -d option only
performs the download, it does not search and update the listing of installed
applications. Using the --cve option will update the CVE data files instead
of the normal repositories.

appupdater --upgrade [-y] [--no-silent] [-d]

Perform an upgrade of all known applications if available. The -y option
will automatically answer yes to the prompt. The --no-silent option will
install packages that require a user interface, this should NEVER be used in
scripts. The -d option will only download the packages, not install. If you
do not want to install all of the upgrades, you will need to do them
indivdually with the --install command or add packages to the IGNORE list in
the config file.
appupdater --clean
Erase cached files. This will remove the XML pacakge information and any
install files. You will need to run --update after this.

appupdater --list [--cve] [-g]

Show the list of installed packages and their versions. Using the --cve
option is slower, but will show known vulnerabilities. Using the -g option
will show package groups.

appupdater --version [--full]

Displays the program version and copyright information. Using the full
option will output all internal configuration which is useful for debugging
purposes.

appupdater --available [--full] [--cve] [-g]

List packages available to install. The --full option lists all versions,
not just the current versions. Using the --cve option is slower, but will
show known vulnerabilities. Using the -g option will show package groups.

appupdater --install PKG [--no-silent] [-d] [-i VERSION] [--force] [-g]

Install a new package by name. If the package name has a space in it you
will need to surround the name by quotes. Options have the same meaning as
in for --update. VERSION is optional, and is the number that appears when
using --available. If a package is already installed, use --force to install
it anyway. If no exact match is found, the newest version of the package is
installed. Using the -g option will install package groups.

appupdater --remove PKG [--no-silent] [-i VERSION] [-y] [-g]

Remove a package by name. If the package name has a space in it you
will need to surround the name by quotes. Options have the same meaning as
in for --install. VERSION is optional, and is the number that appears when
using --available. If no exact match is found, the newest version of the
package is removed. Using the -g option will remove package groups.

appupdater --info PKG [-i VERSION] [--cve] [-g]

Get information about a package by name. If the package name has a space in
it you will need to surround the name by quotes. VERSION is optional, and is
the number that appears when using --available. If no exact match is found,
the newest version of the package is installed. Using the --cve option is
slower, but will show known vulnerabilities. Using the -g option will show
the packages in a group.

appupdater --run PKG

This will automatically start the main program for the package. It assumes
it already installed. You should run --install to be sure. If the package
name has a space in it you will need to surround the name by quotes.

appupdater --load FILE [-d] [--force] [-g]

Install new packages from a text file named FILE. This can be a local file
or a URL. Text file format is the same as the output from --dump, one
package per line. Optionally, the version can be tab delimited after the
package name. Comments can be added by starting the line with #. Using the
-g option will read in the package group names.

appupdater --dump FILE [-g]

Generate a file named FILE with the currently installed applications and
versions. Using the -g option will write out the package group names.

appupdater --add
Add new repositories that are suggested by repositories you are currently
using. You will be given a list to choose from and have the ability to add
individual repositories or just add them all.

appupdater --config CONFIGFILE

Specify a config file to use, named CONFIGFILE. This can be used in
combination with any of the other commands discussed. If this is NOT set,
the program automatically loads config files from the following places in
order of priority, /etc/appupdater.ini, ~/.appupdater.ini, appupdater.ini,
config.ini. The last two are in the directory where the program executable
is located. See the config-sample.ini for documentation on what
configuration options are available.

appupdater --dryrun
This can be used in combination with any of the other commands discussed.
This will not make any real changes, just act as though it does in order for
you to preview what will happen when actually run. This can be especially
useful with --install if you are concerned about security.

appupdater --user
This can be used in combination with any of the other commands discussed.
This will limit Appupdater config and temp files to the current user home
directory (or the same directory Appupdater is installed to). This will
not allow editing of systemwide configuration files.

4.2. Windows Service

--------------------
The Windows Service is designed for completely automated installation
systems, perhaps in a corporate environment. Its sole function in life is to
download XML database updates, index the installed files on the local system,
and upgrade those when new versions become available.

You will probably want to use your own config.ini file, but it is not
required. You should look at setting the following values:

REPORTING - This is on by default, can create privacy concerns

AUTO_DOWNLOAD - Automatically download updates, manually install later
AUTO_INSTALL - Automatically download and install updates
UPDATE_EXPIRE - How often to download update XML databases to the system
INDEX_HOUR - Preferred time of day to update the system
PACKAGE_LISTS - List of text files that contain packages to automatically install

The Windows Service interacts with the desktop via a system tray icon. When
the service is performing updates it will provide notification popups through
the tray icon. Right click and it will also provide a menu of handy
functions.

4.3. Portable (USB Drive)

-------------------------
The documentation and usage previously described also applies in this case.
Make sure to run --update first on EACH computer to make sure the inventory
gets updated properly. If you installed using the installer program,
Appupdater is correctly configured for a portable device and will download
installation files to the portable device.

If you did not use the installer, you should consider setting the following
configuration values. By default temporary files are stored on the hard
drive. If you have a large USB drive you may want to set CACHE_DIR to
"cache" so that the files are saved on the portable device. This prevents
having to download installation files on every computer that it is used on.

CACHE_DIR - directory for storing downloaded files and internal program information
TEMP_DIR - place to store temporary files

4.4 Graphical User Interface (GUI)

----------------------------------
Appupdater now ships with two GUI types, one based on Tcl/Tk and another
based on Qt. By default the Qt version is used. Options include:

appupdaterw --tk
This will force Appupdater to run with the Tk version only. This is the most
compatible GUI because python.org ships with it included.

appupdaterw --qt
This will force Appupdater to run with the Qt version only. This Requires
PyQt to be installed on your system.

5. ENTERPRISE DEPLOYMENT
========================
Enterprise deployment is really easy. Having your own XML files is not
required, but will be the only way to deliver non-freely available
applications. See the next section for information on that.

1. First you need to install Appupdater on each computer.

2. You should only use one of these methods! If you run both and they are
loading different configuration files you may have serious problems.

2.a. Have a script run whenever you want to push new applications, perhaps daily:
appupdater --update --config Myconfigfile
appupdater --load Myfilepath --config Myconfigfile

- OR -

2.b. Use the Windows Service, see section 3.2.

Myfilepath can be a file on the local computer, on a network drive, or on a

HTTP/FTP server. The advantage to having it on a network server is that you
can change the file in one place and packages will automatically be deployed
to each workstation. You can also have a different Myfilepath for each
workstation type for different package set deployments, or even a different
file for every workstation. You should be sure to include version numbers
in Myfilepath if you do not want systems automatically upgrading to the
newest versions.

You will probably want to use your own config.ini file, but it is not
required. The same rules apply as for Myfilepath. You should look at
setting the following values:

REPORTING - This is on by default, can create privacy concerns

6. CREATING YOUR OWN REPOSITORY

===============================
6.1. Requirements
-----------------
- Some type of file server (HTTP, FTP, Windows/Samba)
There are two XML files used:
1. apps.xml - This contains basic program information, including what files
to search for and what programs that are associated with them
2. versions.xml - This contains more detailed information, there is any entry
for each version of a program

XML format is documented in XML.txt. versions.xml is a superset of the

metalinker standard, http://www.metalinker.org/.

For the client setup you should review ENTERPRISE DEPLOYMENT. You will need
to use your own config.ini file and set APPS_XML at a minimum. You should
also look at setting the following values:

APPS_XML - This needs to be set to load the XML file from your repository
REPORTING - This is on by default, can create privacy concerns, but it can
also provide valuable feedback on new applications if you are running a HTTP
server with scripting
UNKNOWN_TXT - Alternatively you might want to set this to a shared network
directory if you don't have a HTTP server for REPORTING
UPDATE_EXPIRE - You may want to lower this time if you want more rapid
deployment cycles.

6.2. Tools
----------
appupdateri - This package ships with an inventory tool (appupdateri) to
create a baseline of what applications are currently installed on the
system. It searches for .exe files in directories where they are normally
found and generates inventory.xml, which can easily be used as an apps.xml
template. Use the APPS_XML option to point appupdater to this file and run
appupdater --update, then appupdater --list. You will then find a file
called unknown.txt in the cache directory that contains information useful
for creating your custom versions.xml file.

Metalink Editor (http://hampus.vox.nu/metalink/) - Used to create the

metalink portions of the XML file.

Appupdater Server Tools - Used to combine Metalink files and version

information, available from:
http://appupdater.svn.sourceforge.net/viewvc/appupdater/server_tools/

7. PERMISSIONS
==============
Appupdater operates in two modes depending on which mode it is started in,
"system" and "user." You can control access to who can manipulate the
service using file permissions.

By default, if the application can read and write to system files

/etc/appupdater.ini or %PROGRAMDATA%\Appupdater\appupdater.ini it operates in
a "systemwide" mode. These are "system" configuration files used to control
the Windows Service which runs as administrator. If the user starting
Appupdater does not have permissions to read and write to those files, it
will default to "user" mode.

Appupdater can be forced to start in "user" mode by passing the --user

parameter or using the "Appupdater as user" shortcut. This places a
configuration file in the home directory (~/.appupdater.ini) and Appupdater
will not be able to manipulate the Windows Service (Background tab) in this
mode.
8. KNOWN ISSUES
===============
- Installer will not be able to write to some files if the Computer
Management screen is open. Close the Computer Management screen to solve
this problem.
- Due to an NSIS limitation, your PATH statment cannot be longer than 1024
characters. If it is it will be ignored on install and you will have to add
it to your system path manually.
- If you installed with the Source Code option before version 0.6, the old
code will continue to be used. Solution is to uninstall/reinstall or remove
all of the .py files from the installation directory.