Installation

System Requirements

Alpas has only a few system requirements. The requirements vary based on whether you want to set up a machine for development or for production.

Development

Alpas is easy to get started with on any *nix based machines; all you need is a JDK. Windows is supported but only under WSL or using GitBash.

  • macOS or Linux
  • Windows support is only available with WSL or GitBash.
  • JDK >= 9.0
  • Gradle >= 5.6
  • IntelliJ IDEA Community or Ultimate (Optional, but highly recommended)

/watch/ Watch Setting up GitBash and SDKMan on Windows and Alpas Installation on Windows With WSL by AlpasCasts.

/info/ You need a GitHub account to create your project based on Alpas’s starter template. Once created, you can host your project anywhere you would like.

Production

If you have created a fat JAR file for serving your app, the only requirement is the Java Runtime jre. If you intend to run some Alpas console commands, such as alpas migrate, then you can set up your prod machine as if it was your dev machine.

Setup

Using sdkman

You can install Alpas system requirements anyway you want. However, because of its simplicity and being able to manage multiple versions, we highly recommend using sdkman.

  1. Install sdkman: curl -s "https://get.sdkman.io" | bash
  2. Restart the terminal or just source the sdk: source ~/.sdkman/bin/sdkman-init.sh
  3. Check the version to be sure: sdk version
  4. Install the minimum version of Java required: sdk install java 9.0.7-zulu
  5. Install the minimum version of gradle required: sdk install gradle 5.6.4

Installation

After you have set up your machine, it only takes a few steps to have your new Alpas app up and running:

Creating New Project

  1. Visit Alpas starter repo on GitHub and click the green Use this template button.
  2. Give it a name. Once done, clone your new repo on your local machine.
  3. At the root of the project there is a script named alpas. Make it executable: chmod +x ./alpas
  4. Initialize your new project using the full package name: ./alpas init com.example.myapp
  5. Once done, to run your app, do: ./alpas serve
  6. Open your new project in IntelliJ IDEA. Optional but very highly recommended!

Configuring

Once the new app is initialized, you can start configuring your app. Start with the .env file that is automatically created under the project’s root directory during the initialization.

Running

Running from the Command Line

You can serve your app from the command line or import it in IntelliJ IDEA and then run it from within the IDE. To serve it from the command line, use: ./alpas serve. If everything goes well, your web app will be available at http://localhost:8080

Running from IntelliJ

To run with IntelliJ, you will need to ensure the project is setup to run Java 9.

  1. To check, click on File > Project Structure > Project and see what is selected for Project SDK.
  2. To switch to Java 9, from the same window, click Platform Settings > SDKs > + > Add SDK and then locate the path to where the Java 9 folder is located. If you installed Java 9 using sdkman per the setup instructions above, then the path is likely ~/.sdkman/candidates/java.

Once you have added JDK 9, go back to step one and select Java 9.

To run the project in IntelliJ, use the project navigation to select src/main/kotlin/start.kt and right-click > Run.... You can also open this file instead and hit the green play (►) button. If everything goes well, your web app will be available at http://localhost:8080

/watch/ Watch Installing IntelliJ IDEA and Serving an Alpas App on Mac by AlpasCasts.

Serving Over the Network

By default, when you serve your web app it is available at http://localhost:<port>. Sometimes it is very convenient to have your web app accessible from a different device on the same network. This is very helpful during development especially if you are trying to access your web app from a mobile device for, say, testing and debugging the app’s UI.

Alpas makes it really easy to serve your web app over an IP address. To do so set ENABLE_NETWORK_SHARE to true in your .env file. Build and re-serve your app and it should be available from both http://localhost:<port> and http://<local-device-ip>:<port>.

/alert/ All the new apps are by default initialized to serve from port 8080. You will get an error if the port is already in use. If you want to use a different port, change the APP_PORT value in your .env file.

Auto Port Selection

You can set the port on which your app gets served in your .env file. However, the port you have set in your .env file may not always be available as there could be another app already running on that port.

In order to not throw an error and to not force you to make a temporary change in your .env file, in development mode, Alpas automatically selects a different port in case that port is busy.

When you run your app again, if the selected port is free, it switches back to the original port otherwise it continues to serve on a temporary port. Pay attention to the port address printed on the console to know which temporary port is selected to serve your application. This temporary port selection is not available in production mode.

/power/ Alpas runs on an embedded Jetty Web Server.

Next Topic