Get Started with ASE
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!
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
-
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 to use:
-
Set the value of
host
to be the hostname of your Fusion, e.g.host: localhost
orhost: fusion.example.com
-
Set the value of
port
to be the port of your Fusion - this is6764
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 calledMyAwesomeApp
, then you will have a default Query Profile calledMyAwesomeApp
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
becomescollection: MyAwesomeApp_user_prefs
. This configures the Appkit SDK to store social data in theCOLLECTION_NAME_user_prefs
sidecar collection associated withMyAwesomeApp
.
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
See Additional script commands for more commands. |
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:
<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 thetitle_s
field as the displayed title text for each result. If your document titles are stored in a different field, replacetitle_s
with the name of that field. -
urlfield="id"
configures the application to use the value of theid
field as the hyperlink - when users click on the title, they will be navigated to whatever URL is in theid
field for that result. If your document URLs are stored in a different field, replaceid
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:
<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 thedescription_s
field for the description text of each search result. If your descriptions are stored in a different field, replaceid
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:
<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:
-
Import the project into IntelliJ
-
Add a new Maven "Run Configuration" - from the "Run" menu, select "Edit Configurations". Click the "+" button, and select "Maven" from the dropdown.
-
Enter a name for your configuration - e.g. "Jetty Run"
-
Enter the following for the "Command Line":
clean jetty:run -Pdevelopment --settings ./bin/settings.xml -Dtwigkit.conf.watch=true
, then click "Ok". -
Make sure that you are not already running App Studio Enterprise.
-
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>'"
-
As App Studio Enterprise starts, you will see the console output within your IDE
We are now set up to hot reload Java files:
-
Edit a Java file
-
Save the file
-
From the "Build" menu, select "Recompile <your class name>.java"
-
You will see a popup notifying you that a class file has changed, and asking if you would like to reload classes - click "Yes".
-
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/
Additional script commands
Each command and flag is also applicable to the batch script on windows. === start |
./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
./app-studio stop [-p port] [-V]
-p <port>
Specify the port the App Studio HTTP listener is bound to.
package
./app-studio package [-P profile]
-P <profile>
Specify the Appkit profile to use when App Studio is packaged; defaults to development.
This command will build a new JAR and WAR file with App Studio and place it in ./dist .
|
docker
./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.
<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
.
.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.
// 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.