Getting Started
---------------

Prerequisites
~~~~~~~~~~~~~

The Artificer application is written in Java. To get started make sure your system has the following:

* Java JDK 1.7 or newer
* Maven 3.0.3 or newer to build and run the examples
* EE application sever: WildFly (http://www.wildfly.org/downloads) or JBoss EAP (http://www.jboss.org/jbossas/downloads)

Download
~~~~~~~~

The `artificer-<version>.zip` (or tar.gz) archive can be downloaded from the
http://artificer.jboss.org/downloads.html[website]
website. Grab the latest and extract it.

Artificer Installation
~~~~~~~~~~~~~~~~~~~~~~

From the unpacked distribution, run:

....
./install.sh
or
install.bat
....

Alternatively, if you have Apache Ant 1.7 (or later) installed, simply run 'ant'.

The installer will ask you to choose a runtime platform.  Currently the following platforms are supported:

* WildFly 8
* JBoss EAP 6.4

Simply follow the installer instructions to install onto the platform of your choice.  We recommend installing
into a clean version of whatever platform you choose, to minimize the risk of colliding with other projects.
Note that you must have already downloaded and installed the platform on which you wish to run

Finally, please make sure the JBoss admin password you choose (the installer will prompt you for this) contains
letters, numbers, and punctuation (and is at least 8 characters long).

TIP: Read the installer output carefully - extra instructions are given for certain platforms.

User Management
~~~~~~~~~~~~~~~

The Artificer WARs are protected using web application security mechanisms
configured in the web.xml.  By default, Artificer uses single-sign-on (SSO) as the actual authentication
mechanism.  The SSO is provided via integration with the Keycloak framework, a powerful out-of-the-box auth solution.
The actual web.xml configuration uses a standard basic security-context, but SSO
is provided under-the-hood.

The Artificer distribution ships with a *artificer-realm.json* file that's completely pre-configured and can be
directly imported into Keycloak.  Startup WildFly/EAP and visit *localhost:8080/auth/admin/master/console/#/create/realm*.  The initial
administrator account uses "admin" for both the username and password.  There, you can upload the *artificer-realm.json*
file and tweak the realm/accounts.  Note that you can also import the realm the first time you start up WildFly/EAP.
Simply include the following argument:

....
bin/standalone.sh -c standalone-full.xml -Dkeycloak.import=[ARTIFICER HOME]/artificer-realm.json
....

By default, the realm import creates an "admin" user (password: "artificer1!").  This user is used to access the Artificer
server, UI, shell, and other tools.  Again, the user is configurable through the Keycloak admin console.

Feel free to manually create a realm for scratch.  However, there are a few requirements
(see *artificer-realm.json* for example values):

1. The realm must be named *artificer*
2. Defined applications must include *artificer-server* and *artificer-ui*
3. To use our themed login page, use *artificer* for the *loginTheme*
4. Each user must have at least *admin* and *user* values for the *realmRole*

DDL
~~~

Artificer uses RDBMS (through JPA) for all persistence.  The distribution ships with DDL SQL files for the "big 5"
databases: Postgres, MySQL, Oracle, SQL Server, and DB2/IBM.  In addition, H2 is included (the default DB
in WildFly/EAP).

During installation, a simple, file-based H2 datasource is automatically deployed.
(see `$JBOSS_HOME/standalone/deployments/artificer-h2-ds.xml`).  If you use something other than that datasource, be sure to update the
relevant connection properties in `artificer.properties`.  See the "Artificer Server Configuration" section for more details.

To install the DDL, you have two options.  Obviously, manually importing it, using your favorite SQL client, is great.
We're fans of http://www.squirrelsql.org/[SQuirreL]).
As an example, if you install SQuirreL and its H2 plugin, then start WildFly/EAP with Artificer installed,
you could connect to its H2 datasource with the following connection URL.  Use it to import the DDL SQL.

....
jdbc:h2:[JBOSS_HOME]/standalone/data/h2/artificer;mvcc=true
....

Alternatively, Artificer will automatically install the DDL for you.  On startup, it checks to see if the necessary
tables exist.  If not, it will automatically execute the DDL SQL for the DB you've selected in `artificer.properties`.

Startup
~~~~~~~

Once Artificer is installed and configured on your preferred platform, you should be able to go ahead and start it up.

WildFly & EAP (standalone-full is required)
....
bin/standalone.sh -c standalone-full.xml
....

Check your Installation
~~~~~~~~~~~~~~~~~~~~~~~

To make sure your installation works you can fire up the http://localhost:8080/artificer-ui[artificer-ui]. By default,
the username is "admin" and the password "artificer1!".  You
should see the GUI dashboard and be able to navigate to either the Artifacts or Ontologies management pages:

[[figure-gs-screenshot-of-the-artificer-ui]]
.Welcome screen of the artificer-ui.
image::artificer-ui.png[Screenshot of the artificer-ui]

You can click on `Artifacts` and see a list of files related to the Artificer default workflows.

Alternatively you can fire up the `artificer shell` in the `bin` directory of the distribution:
....
./bin/artificer.sh
....

To connect the shell to the server type `connect` and hit the tab key. It should auto-complete
to say `connect http://localhost:8080/artificer-server` and when hitting the return key
you should be prompted for user credentials.  Use 'admin' and whatever password you entered
during installation.  If this succeeds, the shell cursor/prompt will go from red to green. To 
browse the artifacts in the repository (there will likely not be any) run the following query:

....
artificer> query /s-ramp
Querying the S-RAMP repository:
	/s-ramp
Atom Feed (0 entries)
  Idx                    Type Name
  ---                    ---- ----
....
In later chapters will go into more detail, but if this all worked you can be sure that your installation is in good working order.
