Skip to content
Home > Getting Started

Installing 3forge Enterprise

3forge Enterprise installs as a single directory tree and starts from a script on Linux or from the Windows installer. This page covers prerequisites, downloading the build, the directory layout, the configuration model, and upgrading an existing installation.

Prerequisites

  • Java 8 or later on Linux, installed on the machine that runs AmiCore. The Windows installer includes its own Java runtime, so Windows needs no separate Java installation.
  • Permission to install software on that machine.
  • Network access from the machine to your data sources.
  • A 3forge account with an Enterprise entitlement.

Download the Build

3forge Enterprise is downloaded from the 3forge Client Portal.

  1. Log in to the portal at https://portal.3forge.com. If you do not have a login, you can register at this time. You can confirm your status as an Enterprise user in the top-right corner of the portal.
  2. Open "Enterprise download". Choose your operating system and your build. Your regional support team will recommend a specific build based on what you intend to deploy.
  3. The page builds an archive to your selection: operating system, assigned version, and the plugins you need. Plugins are versioned separately from the runtime and can be added later, so you can select them now or return later (see Managed Plugins).
  4. Download your build.

3forge Client Portal Enterprise download page, showing OS/build selection and the plugin picker.

Install and Start

  1. Run the .exe file to start the installation wizard and follow the steps to install. The wizard's final screen offers to launch AmiCore.

    Windows Defender SmartScreen Warning

    You may encounter a Windows Defender SmartScreen warning. If this happens, click on the "More info" pop-up, and select "Run anyway." For older versions of Windows (10 or earlier), right-click on the executable file and go to Properties -> General and under the Security section, check "Unblock."

  2. If the wizard did not launch it, launch "AMI Core" from your Start Menu, or run the amicore.exe application located in the installation's amicore directory.

  3. On first launch, the "AMI - Set Up Credentials" window opens, populated with the default credentials demo / demo123. Replace them with your own username and password, then submit. The window cannot be skipped: AmiCore does not start until a username and password are submitted. This creates the initial admin in data/access.txt and populates the rest of data/. See Security Defaults for how the initial admin is established.

    If the setup window did not appear

    Add the initial admin to the installation's data/access.txt directly, one line per user, in the same format as the Linux tab:

    1
    someuser|somepassword|ISADMIN=true|ISDEV=true|AMIDB_PERMISSIONS=READ,WRITE,ALTER,EXECUTE|AMIADMIN_PERMISSIONS=EXECUTE

    Note

    Submitting the window unchanged creates an admin named demo with the password demo123.

  4. Your browser opens the Web's HTTPS address, https://localhost:33333/. Log in with the username and password you entered in the previous step.

    The page shown after setup lists demo / demo123

    After setup, the page that opens still states that the default login is demo / demo123, even when other credentials were entered. That pair works only if you submitted the setup window unchanged. Log in with the credentials you entered.

  1. Extract the .tar.gz archive into the directory you want to install into:

    1
    tar -xf amicore_unix_<VERSION>_<RELEASE_TYPE>.tar.gz -C <YOUR_TARGET_DIRECTORY>

    The archive extracts to ami/amicore/ inside the target directory. The rest of this page calls ami/amicore/ the installation root.

  2. Change to the installation root:

    1
    cd <YOUR_TARGET_DIRECTORY>/ami/amicore

  3. Create the initial admin credentials in data/access.txt. The archive does not include a data/ directory, so create it first:

    1
2
    mkdir -p data
echo 'someuser|somepassword|ISADMIN=true|ISDEV=true|AMIDB_PERMISSIONS=READ,WRITE,ALTER,EXECUTE|AMIADMIN_PERMISSIONS=EXECUTE' > data/access.txt

    Replace someuser|somepassword with your own username and password.

  4. Navigate to the installation's scripts/ directory and run the startup script:

    1
2
    cd scripts
./start.sh

    Startup fails without access.txt

    Without a valid data/access.txt, start.sh stops and prints the command to run, with the full path to your installation:

    1
2
    STARTUP FAILED. View log/AmiCore.stderr and log/AmiCore.log for details
EXITING WITH CODE 13.  YOU NEED TO ADD A USER, RUN: echo 'someuser|somepassword|ISADMIN=true|ISDEV=true|AMIDB_PERMISSIONS=READ,WRITE,ALTER,EXECUTE|AMIADMIN_PERMISSIONS=EXECUTE' > /path/to/your/ami/amicore/data/access.txt

    Run the printed command with your own username and password, then run start.sh again.

    The script prints a banner while it starts, then reports the paths it is using and the addresses to open:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    Starting 3forge AMI Core (pid=1234).....
Startup complete in 4,403 milliseconds
Visit us at http://3forge.com

Logging: /path/to/your/ami/amicore/log
Scripts: /path/to/your/ami/amicore/scripts
Configs: /path/to/your/ami/amicore/config

To access this AMIDB via JDBC: jdbc:amisql:hostmachine:3280?username=...&password=...
To access this AMIDB via command line: ssh -p 3290 user@hostmachine
To access this web server browse to: http://hostmachine:33332
To access this secure web server browse to: https://hostmachine:33333
To access this admin console via command line: ssh -p 3285 user@hostmachine
Default Username: demo
Default Password: demo123

    Note

    The scripts may need executable permissions. If so, run chmod +x *.sh in the scripts/ directory.

  5. Open the secure web server address printed by the script. By default this is https://localhost:33333/.

  6. Log in with the credentials you created in data/access.txt. Ignore the banner's last two lines: the demo / demo123 pair it prints does not work, see Security Defaults.

The HTTP address redirects to HTTPS

TLS is enabled by default, so the HTTP listener on 33332 does not serve the application. Every request is redirected to the same path on the HTTPS listener on 33333, preserving the host you asked for.

On a fresh install that certificate is self-signed, so your browser shows a certificate warning the first time you connect. This is expected on a new instance. See Server Certificates for how to replace the shipped certificate, and Security Defaults for the rest of the shipped security posture.

Changing the Java Version on Linux

On first startup, start.sh detects the Java version and writes JVM options to match in amicore_linux.vmoptions, in the installation root. It starts without additional configuration in most cases. This section applies to Linux only: the Windows installer runs its own included Java runtime.

If you change or update the Java version afterward, the generated options may become incompatible with the new version, causing the JVM to fail to build. For example, options generated for Java 11 fail on Java 8: start.sh reports STARTUP FAILED. View log/AmiCore.stderr and log/AmiCore.log for details, and the installation's log/AmiCore.stderr ends with:

1
2
3
Unrecognized option: -Xlog:gc:log/gc.log:time,uptime,level,tags,tid
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

To resolve this, delete amicore_linux.vmoptions from the installation root and run start.sh again. The script regenerates the file for the Java version now in use.

To run AmiCore under a specific Java installation when several are present, replace every java command in scripts/start.sh with the full path to the Java version you want. The script calls java in 5 places, including the line that detects the version, so replacing only some of them detects one Java and runs another. From the installation root, for example:

1
sed -i 's#\bjava #/usr/lib/jvm/java-11-openjdk-amd64/bin/java #g' scripts/start.sh

Then delete amicore_linux.vmoptions if it exists, and run start.sh. An upgrade replaces scripts/start.sh, so repeat the edit after upgrading.

Minimum Environment

Component Minimum Suggested
Operating system Ubuntu, Fedora/Red Hat, CentOS, macOS, Windows (full support for Java 8 or later) Unix environment with Java 8 or later
RAM 4 GB 32 GB or more
Disk 20 GB 100 GB or more
Processor 2 GHz CPU (Intel or AMD) 3 GHz CPU, 8 cores or more
Client browser Up-to-date Microsoft Edge, Chrome, Firefox, or Safari Same
Network Server must reach data sources; firewalls must allow connections to the Web listener port Same

Lowering the maximum heap on Linux

On Linux, start.sh writes amicore_linux.vmoptions with a maximum heap of 19 GB (-Xmx19g) the first time it runs, including a run that fails. On a machine near the minimum specification above, lower it:

  1. Run start.sh once so the file exists, then stop AmiCore with scripts/stop.sh.
  2. Edit the -Xmx19g line in amicore_linux.vmoptions, for example to -Xmx2g.
  3. Run start.sh again.

An upgrade keeps amicore_linux.vmoptions, so the change survives it.

Directory Layout

The installation is a single directory tree under amicore/. On Linux it sits inside ami/ in the directory you extracted to; on Windows it sits in the installation folder you chose, beside the included jre/.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
amicore/
├── amicore.exe                # Windows launcher
├── amicore.vmoptions          # Windows launcher JVM options
├── amicore_linux.vmoptions    # Linux JVM options, written by start.sh on first run
├── config/                    # configuration files
│   ├── 3fsecurity.properties  # JVM security properties
│   ├── build.properties       # build version properties
│   ├── defaults.properties    # shipped, do not edit
│   ├── local.properties       # your overrides (create if absent)
│   ├── root.properties        # load order of property files
│   └── speedlogger.properties # logging properties
├── data/                      # working data, hot-reloaded at runtime; created on first start
│   ├── autosave/              # directory for user autosaves
│   │   └── ...
│   ├── cloud/                 # directory for layouts saved in the cloud
│   │   ├── my_layout.ami
│   │   └── ...
│   ├── idfountain/            # directory for managing auto incrementing ids
│   │   └── ...
│   ├── styles/                # optional, for your own styles; not created by the installer
│   │   └── ...                # shipped styles are bundled in lib/amicore.jar, not here
│   ├── users/                 # directory for user preferences
│   │   ├── user.ami_settings
│   │   └── ...
│   ├── access.txt             # credential store
│   ├── ami.components         # components file: the components this instance runs
│   ├── headless.txt           # headless session details
│   ├── managed_schema.amisql  # managed schema
│   ├── relay.feedhandlers     # connected feed handlers
│   ├── relay.method           # Relay method file
│   ├── relay.method.rules     # Relay method rules
│   ├── relay.routes           # Relay routing file
│   ├── relay.transforms       # Relay transforms
│   └── ...                    # styles and other routing files
├── history/
│   └── ami_console.history    # 3forge command line history
├── keys/                      # keystores, public keys, and the client allowlist
│   ├── 3forge.auth            # authorized-clients allowlist, one ssh-rsa key per line
│   ├── 3forge.jks             # native-listener keystore (Center, JDBC, Relay, Gateway)
│   ├── 3forge.pem             # Web HTTPS keystore
│   ├── 3forge.pem.pub
│   └── 3forge.pub             # server public key, ssh-rsa
├── lib/
│   └── amicore.jar            # the consolidated runtime library
├── log/                       # log output, files with numbered extensions are logs from past runs, unnumbered files are the most recent logs
│   ├── AmiCore.log            # log of all messages received by 3forge
│   ├── AmiCore.stats          # log of runtime statistics
│   ├── AmiAi.log              # log of AI messages
│   ├── AmiMessages.log        # log of realtime messages sent to and from AMI
│   └── ...
├── persist/                   # persisted table state
│   ├── __CENTER.dat           # information on connected Centers
│   ├── __DATASOURCE.dat       # information on available datasources
│   ├── __REPLICATION.dat      # information on replication Centers
│   └── amikey.aes             # the encryption key file
├── plugins/                   # installed plugin bundles, one isolated classloader each
├── resources/
└── scripts/                   # UNIX/DOS scripts for starting/stopping 3forge
    ├── start.sh
    ├── stop.sh
    └── ...                    # other tools

Configuration Model

3forge Enterprise separates shipped defaults from your overrides.

  • Never edit config/defaults.properties. The runtime compares it against an embedded copy at startup and reports drift, controlled by -Dvalidate.default.properties=WARN|EXIT|SKIP (the startup script sets WARN).

  • Put every override in config/local.properties. To extend a shipped list rather than replace it, reference the existing value:

    1
    ami.datasource.plugins=$${ami.datasource.plugins},PLUGINNAME

  • Most files under data/ are watched and hot-reloaded at runtime, including ami.components, relay.routes, and relay.feedhandlers, so day-to-day changes do not require a restart. Shut down first only when you want to coordinate changes across multiple files.

Default listener ports

By default, AmiCore assigns the following listener ports:

  • Center: 3270 (native)
    • JDBC: 3280
    • DB Console: 3290
  • Relay: 3289
  • Web (HTTP): 33332 (redirects to HTTPS)
  • Web (HTTPS): 33333
  • f1 admin console: 3285

The Gateway's ports, 3406 (native) and 3407 (JDBC), are configured by default, but a new installation does not run a Gateway: its components file declares only a Center, a Relay, and a Web. To add one, see the Gateway Quickstart.

The full component and port reference is in Components.

Upgrading AmiCore

An upgrade installs a new build over an existing installation, replacing the runtime and keeping your data, credentials, and configuration overrides.

Warning

Running an upgrade is not reversible and will overwrite the shipped files in your existing installation. We strongly recommend backing up the installation directory before proceeding.

An upgrade keeps:

  • data/, including access.txt
  • persist/
  • keys/
  • config/local.properties
  • amicore_linux.vmoptions (Linux)
  • f1license.txt, the license file

An upgrade replaces:

  • lib/
  • config/, except local.properties
  • scripts/, including any edits to start.sh
  • amicore.exe and the included jre/ (Windows)

Note

If you have a modified start.sh, copy it elsewhere before upgrading and reapply your changes afterward.

  1. Stop AmiCore.
  2. Run the new build's .exe file. The wizard selects the folder of the previous installation.
  3. Keep that folder to upgrade in place, or choose a new folder to install the new build separately beside the old one.
  4. Follow the remaining steps and launch AmiCore from the final screen.

  1. Stop AmiCore from the installation's scripts/ directory:

    1
    ./stop.sh

  2. Extract the new archive into the same directory you extracted the existing installation into:

    1
    tar -xf amicore_unix_<VERSION>_<RELEASE_TYPE>.tar.gz -C <YOUR_TARGET_DIRECTORY>

  3. Reapply any changes to scripts/start.sh, then run start.sh.

Plugins are versioned separately from the runtime. After upgrading, check that your plugins match the new build; see Managed Plugins.

Next Steps

  • Security Defaults: the initial admin, TLS, and the file-system sandbox.
  • Server Certificates: replacing the shipped self-signed certificate, needed before most clients will connect over TLS.
  • Licensing: create and install a license (without one, the instance runs in demo mode and shuts down after 2 hours).
  • What's New in 3forge Enterprise: if you are migrating an existing application, what to copy and what not to.