Search

⚙️

Anchor Local CASS Install

Install Anchor MaxCASS Plus on your Linux host and connect it to BettrData’s local CASS workflow.

Scope: Unpack the Anchor download, install the software and postal data, configure local processing, and verify the installation. General BettrData platform installation and startup are covered separately.

📌

This guide covers CASS address validation only: DPV processing. NCOA processing, RDI, and geocoding are not included for this setup.

Before you begin

Have these items ready:

  • The Linux MaxCASS Plus download supplied by Anchor, including the product and postal-data bundles.
  • The exact company name and 30-character security ID issued by BettrData.
  • Administrator access with sudo on the Linux host.
  • A BettrData release that supports ANCHOR_LOCAL, including the current local controlbook and worker integration.
  • Access to your BettrData cooker container, with the included setup-local.sh installer. Copy the script to the host in Step 2. Keep the supplied smoke-test files available for verification.
  • Sufficient disk space for the product, postal databases, and temporary job output.

Run host commands on the same machine that runs the BettrData cooker container. Replace example paths with your installation paths. Never put a security ID or credential in a support ticket, screenshot, or this guide.

1. Unpack the Anchor download

Extract the vendor ZIP into a dedicated folder:

mkdir -p "$HOME/anchor-install"
unzip "/path/to/Anchor-MaxCASS.zip" -d "$HOME/anchor-install"

Locate the folder containing the installer and both package folders. The layout should resemble:

anchor-install/
├── Anchor_Installer_User_Guide.pdf
├── anchor-software-installer-1.2.7.tar.gz
├── MaxCASSPlus/
│   └── MaxCASSPlus_1.3.9.0.tar
├── MaxCASSPlusData/
│   └── MaxCASSPlus_Data_<customer>_1.3.9.0.tar
└── MaxCASSPlusSample/
    ├── CASS.zp4
    └── INPUT_FLAT.DAT

Version numbers and customer filenames may differ. Keep the inner .tar and .tar.gz packages intact; the setup helper installs them for you.

If the ZIP creates an additional top-level folder, use that folder as PACKAGE_DIR below.

2. Copy the installer from Docker and run it on the host

Use the installer included in your BettrData cooker image. Run the following commands on the Linux host, not inside the container. Replace bettrdata-cooker-1 if your cooker container has a different name.

Find the installer in the running cooker container and copy it to the host:

Only continue if the copy succeeds. The container must be running for the discovery command; docker cp copies the file to the host rather than running the installation inside Docker.

The script initializes the Anchor environment when needed, installs the product and postal-data bundles, and prepares the jobs directory. You do not need to run the vendor installers separately.

PACKAGE_DIR="$HOME/anchor-install"
sudo bash "$HOST_INSTALLER" "$PACKAGE_DIR"

The helper defaults the jobs-directory owner to UID/GID 1001:1001. If your deployment uses different worker IDs, pass those exact IDs instead:

sudo BETTRDATA_UID=1000 BETTRDATA_GID=1000 \
  bash "$HOST_INSTALLER" "$PACKAGE_DIR"

The IDs must match the BettrData cooker worker configuration. Do not assume they are always the same as your login account.

During the installer prompts:

  1. Confirm that you want to initialize the Anchor environment.
  2. Enter the company name exactly as Anchor issued it, including capitalization.
  3. Enter the vendor-issued 30-character security ID.
  4. Keep the default shared-data location unless your administrator has planned a different location.
  5. Review and confirm the installation paths.

For the BETTRDATA-issued license used to validate this setup, the company name is BETTRDATA, not “BettrData.” Other customers must use their own vendor-issued name.

The default locations are:

  • Program: /opt/anchor-software/maxcass-plus
  • Shared libraries: /opt/anchor-software/lib
  • Configuration: /etc/opt/anchor-software
  • Product configuration: /etc/opt/anchor-software/maxcass-plus/config.xml
  • Postal data: /var/opt/anchor-software/shared/cass
  • Job links: /opt/anchor-software/maxcass-plus/jobs

Expected result: The helper finishes with “MaxCASS Plus local install is ready.”

A “pending dependencies” message while the product installs can be normal: the postal-data bundle is installed afterward. If the product is still not activated when setup finishes, contact support before continuing.

3. Verify the host installation and DPV security file

Check that the program and security file exist:

sudo test -x /opt/anchor-software/maxcass-plus/bin/maxcassplus && echo "MaxCASS executable found"

sudo ls -l /etc/.acixsec2

/etc/.acixsec2 is the Linux DPV security file used by this installation. It must exist as a regular file and be readable and writable by the cooker worker.

⚠️

If the security file is missing, or DPV reports a lockout, stop and contact Anchor Support. Do not delete the file, create an empty replacement, or run security reset/unlock/bypass commands without Anchor’s instructions. Installation activation does not by itself prove runtime license authorization.

Run the supplied smoke test on the host:

sudo bash shared/tests/anchor/run-maxcass-smoke.sh

Expected result: DPV initializes, all 10 test records are processed, the job completes, and an output CSV is printed.

The script retains its artifacts under a unique /data/cass-smoke-* directory, or /tmp/cass-smoke-* when writable /data is unavailable.

Do not use maxcassplus --help as a CASS validation test: MaxCASS treats that argument as a controlbook filename.

4. Enable local CASS in BettrData

Add or update these entries in the persistent BettrData configuration, normally ~/.bettrdata/.config:

export ADDRESS_SERVICE_TYPE=ANCHOR_LOCAL
export ANCHOR_LOCAL_HOME=/opt/anchor-software/maxcass-plus
export ANCHOR_LOCAL_BINARY=/opt/anchor-software/maxcass-plus/bin/maxcassplus
export ANCHOR_LOCAL_LIBRARY_PATH=/opt/anchor-software/lib
export ANCHOR_LOCAL_ZP4_TEMPLATE=/app/shared/src/scripts/anchor/cass-local.zp4
export ANCHOR_LOCAL_JOBS_DIR=jobs
export ANCHOR_ROOFTOP=false

Use your deployment’s configuration source if it differs. Setting these variables only in an interactive shell does not persist them for future platform launches.

Confirm that the cooker service receives these values through its Compose environment section. Older deployment files may need updating by your administrator.

Use the real MaxCASS binary, not a mock override. Remove any ANCHOR_LOCAL_MOCK setting or mock Compose override from the deployment.

The current local controlbook must:

  • Keep DPV enabled.
  • Disable RDI and adjunct geocoding for this CASS-only setup.
  • Disable LC casing logic and use uppercase output.
  • Run MaxCASS from each job’s writable working directory, not the program installation directory.

These settings are included in the updated BettrData integration. Remote AnchorConnect.ini credentials are not needed for this local CASS workflow.

5. Check the cooker container mounts

Under the cooker service’s existing volumes list, verify these mounts:

volumes:
  - /opt/anchor-software:/opt/anchor-software
  - /etc/opt/anchor-software:/etc/opt/anchor-software:ro
  - /var/opt/anchor-software:/var/opt/anchor-software
  - /etc/.acixsec2:/etc/.acixsec2:rw

Keep the deployment’s other volume entries. If you selected non-default host locations, map those locations to the corresponding container paths.

Important: Mount the specific security file, not the host’s entire /etc directory. Verify the host file exists before creating the container. Keep the security mount writable; do not copy it into the image or commit it to source control.

The jobs directory must be writable by the configured worker UID/GID. Keep the product installation protected; do not recursively loosen permissions on the program or data directories to solve job-output errors.

Have your administrator recreate cooker through your normal platform procedure after changing mounts or environment variables. Restarting an existing container alone does not apply changed mounts. General platform startup is outside this guide.

6. Test inside cooker as the actual worker

After the platform is running, open a cooker shell from its deployment directory:

docker compose exec cooker bash

Inside that shell, confirm the security file is visible:

ls -l /etc/.acixsec2

Then run the smoke test under the same UID/GID as the worker:

setpriv \
  --reuid="${BETTRDATA_UID:-1001}" \
  --regid="${BETTRDATA_GID:-1001}" \
  --init-groups \
  env HOME="${BETTRDATA_HOME:-/data/.home}" \
  ANCHOR_LOCAL_BINARY=/opt/anchor-software/maxcass-plus/bin/maxcassplus \
  bash /app/shared/tests/anchor/run-maxcass-smoke.sh

This assumes the default worker IDs are 1001:1001 when no explicit values are configured; confirm your deployment’s actual IDs first.

Expected result: All 10 records process successfully, DPV is enabled, and the job completes without permission errors. The output CSV includes ZIP, ZIP+4, delivery point, check digit, barcode, and DPV indicators.

A successful root test is useful, but it does not verify worker permissions. Cooker starts with root privileges for setup, then normally drops to the configured BettrData user.

If your packaged release does not include the smoke-test files, request them from BettrData Support rather than substituting the vendor’s flat-file sample into the CSV smoke script.

7. Run a small end-to-end BettrData job

  1. Upload a small CSV containing known deliverable addresses.
  2. Use a conversion configuration with address standardization enabled.
  3. Map address line 1, optional address line 2, city, state, and ZIP. Store ZIP as text so leading zeros are preserved.
  4. Run the conversion normally.

The integration performs three steps: Convert prepares the input → local MaxCASS validates addresses → Humpty combines the results and completes the job.

Confirm the final job output contains:

  • The expected record count after configured header handling and drops.
  • Standardized address values.
  • ZIP, ZIP+4, delivery point, and check digit for successfully coded records.
  • A DPV match result consistent with the MaxCASS return CSV.
  • A completed BettrData conversion and report.

Not every input address will be DPV-confirmed. Missing GEO, RDI, or NCOA values are expected for this setup. MaxCASS layout-report text files are diagnostic artifacts; the current integration reads only the expected address-return CSV.

Troubleshooting

‣
Missing shared library: libadrvrfy_o.so
‣
E2551: Not licensed for MaxCASS Plus
‣
E2107: DPV security error or lockout
‣
Permission errors for ac.cfg, reports, sorting, or job links
‣
Segmentation fault during output casing
‣
MaxCASS succeeds, but all final records show DPV false

Installation complete

Product and postal data are installed and activated.
A real host smoke test completes successfully.
ADDRESS_SERVICE_TYPE=ANCHOR_LOCAL is persisted and passed to cooker.
Program, configuration, data, and DPV security mounts are present.
The non-root cooker smoke test completes successfully.
A small end-to-end job has verified postal fields and DPV results.
Mock mode is off.

Keep postal databases and software updated using packages supplied by Anchor. Store licenses securely, and retain failed-job logs for support without exposing security IDs or security-file contents.