Omeka allows administrators to configure how files are stored (both original
files uploaded to Omeka and the derivative images Omeka creates itself). For
typical users, the default settings are sufficient: files are simply stored
files subdirectory of the Omeka installation and served from there by
the web server, just like any other file in Omeka.
However, if you want or need to store files in a different location, on a
different drive, or even a different server or service, you'll need to do
some configuration. The storage system is configured through the Omeka
Note: storage changes in the configuration get applied immediately, and will affect all operations involving files. If you change storage methods or locations after already working on an Omeka installation for some time, you'll have to take care of moving or copying any pre-existing files to the new location yourself. If you're thinking about using non-standard storage settings, it's often easiest to make that decision up front, before you upload anything.
Omeka's storage system is based on "adapters." An adapter is simply a method for storing and accessing files, and Omeka ships with two adapters out of the box.
The default adapter is the Fileystem adapter, and it just stores files on the local server. If you haven't explicitly chosen an adapter to use, you're using this one, and it's the right choice for most users, especially if you're not sure which you want to use.
The second adapter included with Omeka is the ZendS3 adapter, which uses Zend Framework code for storing files on Amazon's S3 storage service. This is a more complex adapter, and it requires you to sign up for S3, but it can be the right choice if you have constrained local storage and a large set of files to deal with, or just want to store files remotely for whatever reason.
You set the adapter with a line
storage.adapter in the configuration file.
This configuration option accepts the name of an adapter class. For the
built-in adapters, the class name will start with
so the Filesystem adapter would be
Omeka_Storage_Adapter_Filesystem, and the
ZendS3 adapter would be
Omeka_Storage_Adapter_ZendS3. Plugins can add their
own adapters too, and the plugin should document for you how it needs to be
Remember, if you don't explicitly choose an adapter (in other words, if you
don't have a
storage.adapter line in your configuration file) then Omeka
will use the Filesystem adapter.
Each adapter has some options that can be set to change its behavior. These
options differ from adapter to adapter. Adapter options are set with
storage.adapterOptions. lines in the configuration file (for example, to
localDir option for the Filesystem adapter, you'd use a line like
this (obviously with a real path instead):
storage.adapterOptions.localDir = "/local/path/to/store/files"
Filesystem Adapter Options
The directory where files will be stored. If this is not set, the directory
is set to the
files subdirectory of the Omeka installation by default.
Just like is true for
files in a normal installation, whatever directory
you choose here must be readable and writable by the local user Omeka
executes as (often, this is the web server user).
For visitors to be able to see the files, they'll need to be served by a
web server. For the default location, this is taken care of automatically,
as Omeka is already served by your web server along with the files in the
Omeka directory (including the
files subdirectory). When you change
localDir to a custom setting, you almost always also need to set
(see the next heading).
The URL path to the directory given in
localDir. By default, this is the
root URL for the Omeka installation plus
/files, to go along with the
Omeka doesn't do anything by itself to serve files, it just stores them
in the specified directory and calculates the URL for them. A web server like
Apache is required to actually serve the files to users, so you'll need to set
up a server to serve the files from your
localDir. If you choose a
that is within the "document root" of a web server you already have set up, you
may be able to do this without any additional reconfiguration.
This option needs to be an absolute URL, like
Only the URL up to the directory needs to be provided; Omeka will handle the
part of the URL for referring to a specific file and type of file (in other
words, this option is the prefix for the file URLs).
ZendS3 Adapter Options
Unlike the Filesystem adapter, the ZendS3 adapter has several options that are mandatory and have no default. So, to use this adapter, you must also always set at least some settings.
The ZendS3 adapter requires you to have an Amazon S3 bucket set up.
Your AWS access key ID. If you are unsure about what this is or how to get it, refer to Amazon's documentation on credentials.
This option is required.
Your AWS secret access key. If you are unsure about what this is or how to get it, refer to Amazon's documentation on credentials.
This option is required.
The name of the S3 bucket to store files in.
This option is required.
The number of minutes a URL is valid for.
By default, this is infinite. Omeka will generate plain direct URLs to your files stored in S3, which means links that work as long as the file is still there. This requires the bucket to be configured so anonymous users can view the files.
If you instead want to have a locked-down access policy, you can set this setting, which will cause Omeka to generate pre-signed URLs for files stored in S3. The effect is that links to files will only be valid for the configured number of minutes after the URL was created.
The S3 endpoint for the region your bucket is located in.
By default, this is
s3.amazonaws.com, the endpoint for the US-East (N. Virginia)
region. If you're using a different region, you can set the correct endpoint for it
here. Amazon's documentation lists the S3 endpoints for different regions.
Note: The ZendS3 adapter only supports "Version 2" authentication. Regions listed as "Version 4 only" in the linked table cannot be used with the ZendS3 adapter.
Setting the Temporary Directory
There is one storage option that is used regardless of the configured adapter:
This option takes a local path to the directory Omeka should temporarily store files in while initially working on them. Omeka copies files here, and also performs operations like creating thumbnails here. Plugins that work with files as they're uploaded can also access files in this temporary directory.
By default, this is the system default temporary directory, but on some systems
that directory isn't accessible to Omeka and a different directory needs to be
used. In those cases, set the appropriate path with
storage.tempDir in the
Omeka needs to be able to read and write in this directory, just like in the