> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with ASE

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[localhost link]: http://localhost:3000/docs/4/app-studio/concepts/app-studio-enterprise/getting-started

[mintlify link]: https://doc.lucidworks.com/docs/4/app-studio/concepts/app-studio-enterprise/getting-started

[old doc.lw link]: https://doc.lucidworks.com/app-studio/4.2/993

With App Studio Enterprise you can build a mobile-ready enterprise search application in a matter of minutes. Follow the steps below to get up and running!

<LwTemplate />

## Development tools

In building out a search application, we recommend the use of the following tools:

* Java 1.8 JDK
* NodeJS & npm for front-end dependency management

  * NodeJS v16.70.0
  * npm v9.2.0
* An IDE (Intellij, VS Code, Eclipse..)

## Connecting to Fusion

We just need to edit a few config files - fire up your favorite text editor! All of the config files can be found within `src/main/resources/conf`.

Edit `services/api/fusion.conf` - this file controls which Fusion server to use:

* Set the value of `host` to be the hostname of your Fusion server, e.g. `host: localhost` or `host: fusion.example.com`
* Set the value of `port` to be the port of your Fusion server - this is `8764` by default, which is preconfigured for you.

Edit `platforms/fusion/data.conf` - this file configures which data in Fusion to use:

* Replace the text `YOUR_QUERY_PROFILE` with the name of the Fusion Query Profile you wish to direct your queries through. If you have created an app via the Fusion UI called `MyAwesomeApp`, then you will have a default Query Profile called `MyAwesomeApp` as well - this is a good starting point: e.g. `query-profile: MyAwesomeApp`.

Edit `platforms/fusion/social.conf` - this file configures the Lucidworks Appkit Social Module:

* Replace the text `YOUR_FUSION_APP` with the name of your Fusion app, as used above: e.g. `collection: YOUR_FUSION_APP_user_prefs` becomes `collection: MyAwesomeApp_user_prefs`. This configures the Appkit SDK to store social data in the `_user_prefs` sidecar collection associated with `MyAwesomeApp`.

Edit `platforms/fusion/suggestions.conf` - this file configures search suggestions:

* Replace the text `YOUR_QUERY_PROFILE` with the name of the Fusion Query Profile you wish to direct your search suggestion queries through. This can be the same Query Profile as you are using for search queries, e.g. `query-profile: MyAwesomeApp`.

Edit `message/service/fusion.conf` - this file configures how Signals are sent to Fusion:

* Replace the text `YOUR_QUERY_PROFILE` with the name of your query profile, as used above: e.g. `query-profile: MyAwesomeApp`.

## Starting and Stopping

### Linux, Mac OS X

To start the application, run the following command from a terminal:

* `./app-studio start`

To stop the application, run the following command from a terminal:

* `./app-studio stop`

To package the application into a WAR file, run the following command from a terminal:

* `./app-studio package`

### Windows

To start the application, run the following command from a command prompt:

* `app-studio.bat start`

To stop the application, run the following command from a PowerShell command prompt:

* `app-studio.bat stop`

To package the application into a WAR file, run the following command from a command prompt:

* `app-studio.bat package`

<Note>
  See [Additional script commands](#additional-script-commands) for more commands.
</Note>

## Accessing App Studio

Once started, the application is served up at `http://localhost:8080`. You will be asked to authenticate, for which you can use any of your Fusion "native realm" users - if you are just getting started with Fusion, this will be your Fusion `admin` username and password.

When building an application for production environments the security realm can be configured in the `src/main/resources/conf/security/fusion.conf` file.

## Using Your Data

The file `src/main/webapp/views/search.html` defines the main page layout of your application. App Studio Enterprise is pre-configured to work out of the box with Lucidworks Fusion, but you may wish to customize which fields you use in your results.

Let us get started!

### Result title

The title of each result document can be configured like so:

Find the tag that looks like this:

```xml wrap  theme={"dark"}
<search:field name="title_s" styling="title" urlfield="id"></search:field>
```

* `styling="title"` means that it will be used as the result title - no need to change this, but it will help you find the right tag!
* `name="title_s"` configures the application to use the value of the `title_s` field as the displayed title text for each result. If your document titles are stored in a different field, replace `title_s` with the name of that field.
* `urlfield="id"` configures the application to use the value of the `id` field as the hyperlink - when users click on the title, they will be navigated to whatever URL is in the `id` field for that result. If your document URLs are stored in a different field, replace `id` with the name of that field.

### Result description

The text description of each result document can be configured like so:

Find the tag that looks like this:

```xml wrap  theme={"dark"}
<search:field name="description_s" label="Description" max-characters="240" show-more></search:field>
```

* `label="Description"` will help you find the right tag.
* `name="description_s"` configures the application to use the value of the `description_s` field for the description text of each search result. If your descriptions are stored in a different field, replace `id` with the name of that field.

### Facets

Facets are a handy way to refine your search. By default, App Studio Enterprise will attempt to show facets for the `keywords_s` field, if it exists. We can add or remove facets very simply:

Find the tag that looks like this:

```xml wrap  theme={"dark"}
<search:query var="query" parameters="*" results-per-page="12" facets="keywords_s"></search:query>
```

This tag creates the overall page query - `facets="keywords_s"` adds the ability to facet on the `keywords_s` field to the query. We can remove this, or add some more facets - this parameter takes a comma-separated list of field names.

Try `facets="keywords_s,charSet_s"`, or replace the value entirely with a list of your own facet fields.

### Activating your changes

To see your changes in action:

* Save the file
* Refresh your browser
* Yes, that is all!

## Development

### Resources

App Studio Enterprise is preconfigured to automatically reload when you make changes to your code during development.

The following file types are monitored and re-processed when changed:

* HTML (`.html`)
* JavaScript (`.js`)
* LESS (`.less`)
* CSS (`.css`)
* JSP (`.jsp`)
* Config (`*.conf`)

There will be a slight pause between saving the file and being able to view the changes as App Studio Enterprise processes the file.
Refresh your browser after about 2 seconds to see the changes.

### Java

Hot reloading of Java class files requires some extra steps. The Java Virtual Machine supports hot-swapping of class files as long as the changes
are not structural - changes to method bodies and field values are supported, but adding or renaming methods are not.
You will need to use an IDE to set this up - the following steps assume you are using JetBrains IntelliJ IDEA:

1. Import the project into IntelliJ
2. Add a new Maven "Run Configuration" - from the "Run" menu, select "Edit Configurations". Click the "+" button, and select "Maven" from the dropdown.
3. Enter a name for your configuration - e.g. "Jetty Run"
4. Enter the following for the "Command Line": `clean jetty:run -Pdevelopment --settings ./bin/settings.xml -Dtwigkit.conf.watch=true`, then click "Ok".
5. Make sure that you are not already running App Studio Enterprise.
6. From the "Run" menu, click "Debug 'Jetty Run'". If you have named your configuration something other than 'Jetty Run', look for "Debug '\<your configuration name here>'"
7. As App Studio Enterprise starts, you will see the console output within your IDE

We are now set up to hot reload Java files:

1. Edit a Java file
2. Save the file
3. From the "Build" menu, select "Recompile \<your class name>.java"
4. You will see a popup notifying you that a class file has changed, and asking if you would like to reload classes - click "Yes".
5. Your Java change has been deployed into the running Java Virtual Machine - you can now test your running App Studio Enterprise webapp and see your change in action.

## License

App Studio Enterprise comes with a 30-day trial license in `app-studio.lic`. Once this expires, contact Lucidworks for a new license: [https://lucidworks.com/contact/](https://lucidworks.com/contact/)

## Additional script commands

<Note>
  Each command and flag is also applicable to the batch script on windows.
</Note>

### start

```bash theme={"dark"}
./app-studio start [-f] [-p port] [-P profile] [-m memory] [-t timeout] [-V]
```

`-f` Start App Studio in foreground.

`-p <port>` Specify the port to start the App Studio web server on; default is 8080.

`-P <profile>` Specify the Appkit profile to use when App Studio starts; defaults to development.

`-m <memory>` Sets the min (-Xms) and max (-Xmx) heap size for the JVM, such as: -m 4g results in: -Xms4g -Xmx4g; by default, this script sets the heap size to 512m.

`-t <timeout>` Sets the startup timeout in seconds (defaults to 240).

`-V` Verbose messages from the startup script.

### stop

```sh wrap  theme={"dark"}
./app-studio stop [-p port] [-V]
```

`-p <port>` Specify the port the App Studio HTTP listener is bound to.

### package

```sh wrap  theme={"dark"}
./app-studio package [-P profile]
```

`-P <profile>` Specify the Appkit profile to use when App Studio is packaged; defaults to development.

<Note>
  This command will build a new JAR and WAR file with App Studio and place it in `./dist`.
</Note>

### docker

```sh wrap  theme={"dark"}
./app-studio docker [package] [start] [-P profile] [-i image_name]
```

`package` Package App Studio Enterprise then build a Docker image.

`start` Package App Studio Enterprise, build a Docker image, then run a container on port 8080.

`-P <profile>` Specify the Appkit profile to use when App Studio Enterprise is packaged; defaults to development.

`-i <image_name>` Specify the image name to use when App Studio Enterprise is built as a Docker image; defaults to app-studio-enterprise. The image will be tagged as the latest.

## Advanced Configuration

### Add Custom CSS

Add `class` to any component that needs to be customized in an `.html` file.
for example:
`customClass` has been added.

```xml wrap  theme={"dark"}
<search:field name="field_name" label="label" styling="description" class="customClass"></search:field>
```

Then add the custom class in `custom.less` which is located in `src/main/webapp/styles/includes/custom.less`.

```css wrap  theme={"dark"}
.customClass {
    font-weight: bold;
    font-style: normal;
}
```

### Add Custom JavaScript

App Studio is configured out of the box to allow you to simply add your JavaScript inside the controller function in **search.controller.js** and have it trigger and function on every page in your app.

```js wrap  theme={"dark"}
// Print the current page to the console
$scope.currentPage = window.location.href;
console.log($scope.currentPage);
```

### Running the app over SSL

The webapp can also be served over HTTPS using SSL encryption. This is done using the following parameters when invoking the startup scripts:

* `-Dtwigkit.ssl=true` required to turn on secure mode

We include a keystore file with a default self-signed key for development / testing of secure mode. However in order to establish proper trust you will need to import your own valid SSL certificate into the file `keystore.jks` or create your own keystore file. You can then configure SSL via:

* `-Dtwigkit.https.port` optionally sets the HTTPS port (defaults to 8765)
* `-Dtwigkit.http.port` optionally sets the HTTP port (defaults to 8080)
* `-Dtwigkit.keystore.file` keystore filename / location relative to webapp (defaults to 'keystore.jks')
* `-Dtwigkit.keystore.password` password to the keystore (defaults to 'p4ssw0rd')
* `-Dtwigkit.keystore.alias` name of the key in the keystore to be used (defaults to 'default-key')

### Twigcrypt value encryption utility

A best practice that we advocate is to encrypt any sensitive configuration values using our Twigcrypt utility. Twigcrypt’s function is to allow you to quickly encrypt sensitive string values using the command line. These files can be found at `/bin/twigcrypt.zip`.

For more details on how to use Twigcrypt, refer to the README inside the zip file.