# Customization

It is unlikely that the features of the archiver appliance match your
requirements exactly over a period of time. Here are some of the
existing ways that you can customize the archiver appliance (without
forking from the existing source tree).

If you identify other ways in which we can allow for customization of
the archiver appliance to suit your needs, please let the collaboration
know and we\'ll try to accommodate.

## Site specific builds

The archiver appliance offers you the ability to customize the WAR files
generated by the build in these ways.

:::{note}
Han maintains a set of scripts for [site specific installs](https://github.com/jeonghanlee/epicsarchiverap-sites). This is
an excellent starting off point for folks who wish to build their own
deployment bundles. This is tested against CentOS; but should be easily
extensible for other distributions.
:::

1. The `src/sitespecific` folder contains materials specific to your
   site. You can use the environment variable `ARCHAPPL_SITEID` to
   control which set of sitespecific files are included in the
   generated WARS.

   1. When you set this environment variable, you should see a message
      `Building the archiver appliance for the site`{.sample}`YourSite`{.variable}
   2. If this variable is not set, by default, we use the material in
      the `tests` site.
   3. The quickstart package `archappl_vx.x.x.tar.gz` available in the
      Downloads is also built to the `tests` site.
   4. The files in the
      `src/sitespecific/`_`YourSite`_`/classpathfiles` are added to
      the `WEB-INF/classes` of the generated WAR files and should be
      accessible in the code using
      `servletContext.getResourceAsStream("/WEB-INF/classes/<<fileName>>")`
   5. If you do not set the `ARCHAPPL_POLICIES` environment variable,
      the `policies.py` for your site is discovered this way
      1. You can generate WAR with `policies.py` specific to your
         site by setting the `ARCHAPPL_SITEID`.
      2. Or you can unpack the WAR files within the container and
         override the default `policies.py` with your own during
         deployment.
   6. If you do not set the `ARCHAPPL_APPLIANCES` environment
      variable, the `appliances.xml` is discovered in a similar
      fashion.
   7. There is also a site specific properties file called
      `archappl.properties` that is discovered in a similar fashion.
      The properties in this file are used to control some of the
      other customizations of the archiver appliance.

   ```bash
   $ ls -ltr src/sitespecific/
   total 0
   drwxr-xr-x 3 mshankar cd 28 Jun 21 10:40 tests
   drwxr-xr-x 3 mshankar cd 45 Sep  9 16:03 slacdev
   $ export ARCHAPPL_SITEID=slacdev
   $ gradle

   > Configure project :
   [ant:echo] Building the archiver appliance for the site slacdev
   ```

2. The archiver appliance uses [gradle](http://gradle.org) for its
   builds, and [Apache Ant](http://ant.apache.org/) for site specific
   build steps. As part of the gradle build process, you have the
   opportunity to call an ant script that is as part of the
   `src/sitespecific` folder. The `build.xml` in the `src/sitespecific`
   is called (if it exists) after the compile and staging tasks and
   before the WAR is packed. This lets you replace default collateral
   (like images, phone numbers in messages etc) with your own
   collateral in the generated WAR file(s).

3. For simple site specific content changes like replacing the images
   or the contact text in the home page, please see [this document](site_specific).

## Policies

For information on creating and configuring a policies file, see
[Create your policies file](./create-policy-file.md).