add top-level readmes

README.md

@@ -0,0 +1,45 @@
+ArchivesSpace technical documentation
+======================================
+
+* [Basic administration](./administration)
+  * [Getting started](./administration/getting_started.md)
+  * [Running ArchivesSpace as a Unix daemon](./administration/unix_daemon.md)
+  * [Running ArchivesSpace as a Windows service](./administration/windows.md)
+  * [Backup and recovery](./administration/backup.md)
+  * [Re-creating indexes](./administration/indexes.md)
+  * [Resetting passwords](./administration/passwords.md)
+  * [Upgrading](./administration/upgrading.md)
+* [Architecture and components](./architecture)
+  * [JSONModel -- a validated ArchivesSpace record](./architecture/jsonmodel.md)
+  * [The ArchivesSpace backend](./architecture/backend.md)
+  * [Background Jobs](./architecture/background_jobs.md)
+  * [Working with the ArchivesSpace API](./architecture/api.md)
+  * [Search indexing](./architecture/search.md)
+  * [The ArchivesSpace public user interface](./architecture/public.md)
+  * [OAI-PMH interface](./architecture/oai-pmh.md)
+* [Customization and configuration](./customization)
+  * [Configuring ArchivesSpace](./customization/configuration.md)
+  * [Adding support for additional username/password-based authentication backends](./customization/authentication.md)
+  * [Configuring LDAP authentication](./customization/ldap.md)
+  * [ArchivesSpace Plug-ins](./customization/plugins.md)
+  * [Customizing text in ArchivesSpace](./customization/locales.md)
+  * [Theming ArchivesSpace](./customization/theming.md)
+  * [Managing frontend assets with Bower](./customization/bower.md)
+* [Provisioning and server configuration](./provisioning)
+  * [Running ArchivesSpace with load balancing and multiple tenants](./provisioning/clustering.md)
+  * [Serving ArchivesSpace user-facing applications over HTTPS](./provisioning/https.md)
+  * [JMeter Test Group Template](./provisioning/jmeter.md)
+  * [Running ArchivesSpace against MySQL](./provisioning/mysql.md)
+  * [Application monitoring with New Relic](./provisioning/newrelic.md)
+  * [Running ArchivesSpace under a prefix](./provisioning/prefix.md)
+  * [Running ArchivesSpace with external Solr](./provisioning/solr.md)
+  * [Tuning ArchivesSpace](./provisioning/tuning.md)
+* [Information for developers and code contributors](./development)
+  * [ArchivesSpace build system](./development/build.md)
+  * [Building an ArchivesSpace release](./development/release.md)
+  * [Selenium test suite](./development/selenium.md)
+  * [Using Supervisord for development](./development/supervisord.md)
+  * [Contributor license agreements](./development/license_agreements.md)
+* [Importing and exporting data in ArchivesSpace](./import_export)
+  * [ArchivesSpace repository EAD Exporter](./import_export/ead_exporter.md)
+  * [ArchivesSpace XSL stylesheets](./import_export/xsl_stylesheets)

administration/README.md

@@ -0,0 +1,10 @@
+Basic ArchivesSpace administration
+===================================
+
+* [Getting started](./getting_started.md)
+* [Running ArchivesSpace as a Unix daemon](./unix_daemon.md)
+* [Running ArchivesSpace as a Windows service](./windows.md)
+* [Backup and recovery](./backup.md)
+* [Re-creating indexes](./indexes.md)
+* [Resetting passwords](./passwords.md)
+* [Upgrading](./upgrading.md)

administration/backup.md

@@ -0,0 +1,145 @@
+Backup and recovery
+====================
+
+# Creating backups using the provided script
+
+ArchivesSpace provides some simple scripts for backing up a single
+instance to a `.zip` file.  You can run:
+
+     scripts/backup.sh --output /path/to/backup-yyyymmdd.zip
+
+and the script will generate a file containing:
+
+  * A snapshot of the demo database (if you're using the demo
+    database)
+  * A snapshot of the Solr index and related indexer files
+
+If you are running against MySQL and have `mysqldump` installed, you
+can also provide the `--mysqldump` option.  This will read the
+database settings from your configuration file and add a dump of your
+MySQL database to the resulting `.zip` file.
+
+
+# Managing your own backups
+
+If you want more control over your backups, you can develop your own
+scripts.  ArchivesSpace stores all persistent data in the database, so
+as long as you have backups of your database then you can always
+recover.
+
+If you are running MySQL, the `mysqldump` utility can dump the database
+schema and data to a file.  It's a good idea to run this with the
+`--single-transaction` option to avoid locking your database tables
+while your backups run. It is also essential to use the `--routines`
+flag, which will include functions and stored procedures in the
+backup (which ArchivesSpace uses at least for reports).
+
+If you are running with the demo database, you can create periodic
+database snapshots using the following configuration settings:
+
+     # In this example, we create a snapshot at 4am each day and keep
+     # 7 days' worth of backups
+     #
+     # Database snapshots are written to 'data/demo_db_backups' by
+     # default.
+     AppConfig[:demo_db_backup_schedule] = "0 4 \* \* \*"
+     AppConfig[:demo\_db\_backup\_number\_to\_keep] = 7
+
+Solr indexes can always be recreated from the contents of the
+database, but backing them up can reduce your recovery time if
+disaster strikes.  You can create periodic Solr snapshots using the
+following configuration settings:
+
+     # Create one snapshot per hour and keep only one.
+     #
+     # Solr snapshots are written to 'data/solr_backups' by default.
+     AppConfig[:solr_backup_schedule] = "0 \* \* \* \*"
+     AppConfig[:solr\_backup\_number\_to\_keep] = 1
+
+
+# Recovering from backup
+
+When recovering an ArchivesSpace installation from backup, you will
+need to restore:
+
+  * Your database (either the demo database or MySQL)
+  * The search indexes and related indexer files
+
+Of the two, the database backup is the most crucial--search indexes
+are worth restoring if you have backups, but they can be recreated
+from scratch if necessary.
+
+
+## Recovering your database
+
+If you are using MySQL, recovering your database just requires loading
+your `mysqldump` backup into an empty database.  If you are using the
+`scripts/backup.sh` script (described above), this dump file is named
+`mysqldump.sql` in your backup `.zip` file.
+
+To load a MySQL dump file, follow the directions in *Set up your MySQL
+database* to create an empty database with the appropriate
+permissions.  Then, populate the database from your backup file using
+the MySQL client:
+
+    `mysql -uas -p archivesspace < mysqldump.sql`, where
+      `as` is the user name
+      `archivesspace` is the database name
+      `mysqldump.sql` is the mysqldump filename
+
+You will be prompted for the password of the user.
+
+If you are using the demo database, your backup `.zip` file will
+contain a directory called `demo_db_backups`.  Each subdirectory of
+`demo_db_backups` contains a backup of the demo database.  To
+restore from a backup, copy its `archivesspace_demo_db` directory back
+to your ArchivesSpace data directory.  For example:
+
+     cp -a /unpacked/zip/demo_db_backups/demo_db_backup_1373323208_25926/archivesspace_demo_db \
+           /path/to/archivesspace/data/
+
+
+
+## Recovering the search indexes and related indexer files
+
+This step is optional since indexes can be rebuilt from the contents
+of the database.  However, recovering your search indexes can reduce
+the time needed to get your system running again.
+
+The backup `.zip` file contains two directories used by the
+ArchivesSpace indexer:
+
+  * solr.backup-[timestamp]/snapshot.[timestamp] -- a snapshot of the
+    index files.
+  * solr.backup-[timestamp]/indexer_state -- the files used by the
+    indexer to remember what it last indexed.
+
+To restore these directories from backup:
+
+  * Copy your index snapshot to `/path/to/archivesspace/data/solr_index/index`
+  * Copy your indexer_state backup to `/path/to/archivesspace/data/indexer_state`
+
+For example:
+
+     mkdir -p /path/to/archivesspace/data/solr_index
+
+     cp -a /unpacked/zip/solr.backup-26475-1373323208/snapshot.20130709084008464 \
+           /path/to/archivesspace/data/solr_index/index
+
+     cp -a /unpacked/zip/solr.backup-26475-1373323208/indexer_state \
+           /path/to/archivesspace/data/
+
+
+## Checking your search indexes
+
+ArchivesSpace ships with a script that can run Lucene's CheckIndex
+tool for you, verifying that a given Solr index is free from
+corruption.  To test an index, run the following command from your
+`archivesspace` directory:
+
+     # Or scripts/checkindex.bat for Windows
+     scripts/checkindex.sh data/solr_index/index
+
+You can use the same script to check that your Solr backups are valid:
+
+     scripts/checkindex.sh /unpacked/zip/solr.backup-26475-1373323208/snapshot.20130709084008464

administration/getting_started.md

@@ -0,0 +1,75 @@
+Getting started with ArchivesSpace
+===================================
+
+# System requirements
+
+* Java 1.7 or 1.8.
+* At least 1024 MB RAM allocated to the application; at least 2 GB for optimal performance.
+* A [supported browser](https://archivesspace.atlassian.net/wiki/display/ADC/Supported+Browsers)
+
+ArchivesSpace has been tested on Ubuntu Linux, Mac OS X, and
+Windows.
+
+MySQL is not required, but is **strongly** recommended for production use.
+
+**The embedded database is for testing purposes only. You should use MySQL for
+any data intended for production, including data in a test instance that you
+intend to move over to a production instance.**
+
+# Getting started
+
+The quickest way to get ArchivesSpace up and running is to download
+the latest distribution `.zip` file from the following URL:
+
+  https://github.com/archivesspace/archivesspace/releases
+
+You will need to have Java 1.6 (or newer) installed on your machine.
+You can check your Java version by running the command:
+
+     java -version
+
+When you extract the `.zip` file, it will create a directory called
+`archivesspace`.  To run the system, just execute the appropriate
+startup script for your platform.  On Linux and OSX:
+
+     cd /path/to/archivesspace
+     ./archivesspace.sh
+
+and for Windows:
+
+     cd \path\to\archivesspace
+     archivesspace.bat
+
+This will start ArchivesSpace running in foreground mode (so it will
+shut down when you close your terminal window).  Log output will be
+written to the file `logs/archivesspace.out` (by default).
+
+**Note:** If you're running Windows and you get an error message like
+`unable to resolve type 'size_t'` or `no such file to load -- bundler`,
+make sure that there are no spaces in any part of the path name in which the
+ArchivesSpace directory is located.
+
+## Start ArchivesSpace
+
+The first time it starts, the system will take a minute or so to start
+up.  Once it is ready, confirm that ArchivesSpace is running correctly by
+accessing the following URLs in your browser:
+
+  - http://localhost:8089/ -- the backend
+  - http://localhost:8080/ -- the staff interface
+  - http://localhost:8081/ -- the public interface
+  - http://localhost:8082/ -- the OAI-PMH server
+  - http://localhost:8090/ -- the Solr admin console
+
+
+To start using the Staff interface application, log in using the adminstrator
+account:
+
+* Username: `admin`
+* Password: `admin`
+
+Then, you can create a new repository by selecting "System" -> "Manage
+repositories" at the top right hand side of the screen.  From the
+"System" menu, you can perform a variety of administrative tasks, such
+as creating and modifying user accounts.  **Be sure to change the
+"admin" user's password at this time.**

administration/indexes.md

@@ -0,0 +1,11 @@
+Re-creating indexes
+====================
+
+ArchivesSpace keeps track of what has been indexed by using the files
+under `data/indexer_state`.  If these files are missing, the indexer
+assumes that nothing has been indexed and reindexes everything.
+
+To force ArchivesSpace to reindex all records, just delete the
+directory `/path/to/archivesspace/data/indexer_state`.  Since the
+indexing process is cumulative, there's no harm in indexing the same
+document multiple times.

administration/passwords.md

@@ -0,0 +1,12 @@
+Resetting passwords
+====================
+
+Under the `scripts` directory you will find a script that lets you
+reset a user's password.  You can invoke it as:
+
+    scripts/password-reset.sh theusername newpassword  # or password-reset.bat under Windows
+
+If you are running against MySQL, you can use this command to set a
+password while the system is running.  If you are running against the
+demo database, you will need to shutdown ArchivesSpace before running
+this script.

administration/unix_daemon.md

@@ -0,0 +1,25 @@
+Running ArchivesSpace as a Unix daemon
+========================================
+
+The `archivesspace.sh` startup script doubles as an init script.  If
+you run:
+
+     archivesspace.sh start
+
+ArchivesSpace will run in the background as a daemon (logging to
+`logs/archivesspace.out` by default, as before).  You can shut it down with:
+
+     archivesspace.sh stop
+
+You can even install it as a system-wide init script by creating a
+symbolic link:
+
+     cd /etc/init.d
+     ln -s /path/to/your/archivesspace/archivesspace.sh archivesspace
+
+Then use the appropriate tool for your distribution to set up the
+run-level symbolic links (such as `chkconfig` for RedHat or
+`update-rc.d` for Debian-based distributions).
+
+Note that you may want to edit archivesspace.sh to set the account
+that the system runs under, JVM options, and so on.