SPACEPORT DOCS

Developer Onboarding

Getting started as a Spaceport Developer requires minimal setup, but leveraging powerful tools can significantly streamline your experience. Spaceport is built on a robust foundation of open-source components, many of which are integrated directly within the Spaceport JAR. However, some external dependencies and tools are essential for launching Spaceport, maximizing functionality and enhancing your development workflow.

# Prerequisites

To develop with Spaceport, you'll need:

# Java

Spaceport is built on top of the Java Virtual Machine (JVM), and as such, it requires a Java Runtime Environment (JRE) to run. This can be satisfied by installing the Java Development Kit (JDK) or the Java Runtime Environment (JRE). While the JDK is normally recommended for development, Spaceport is built to run on the JRE, so you can use either one.

The requirement for Java is Java 8 SE or higher.

## Installing Java

Installing Java is a simple process, and there are many resources available to help you get started. To check if you have Java installed, run the following command in your terminal:

java -version

If you see a version number, you have Java installed. If not, you can download and install it using your package manager or from the Java SE Downloads page.

Please note: Oracle JDK requires a commercial license for production use, but other drop-in replacements are available for free.

## The OpenJDK Option

If you are able and willing to keep your Java version up to date with the latest rolling releases, using OpenJDK is a good option that is free to use, even in a production setup. Unfortunately, OpenJDK does not have a long-term support (LTS) version, so you will need to periodically update your Java version in order to receive security patches. If you are using a Debian-flavored Linux distribution, you can install OpenJDK using the following command:

sudo apt install default-jre

At the time of this documentation, Java 24 is the current latest version of the OpenJDK release. Spaceport is compatible with this version, but it is currently recommended to use Java 11 for production deployments, as they have the longest long-term support (LTS) available (using Amazon Corretto or Azul Zulu), and the components that Spaceport is built on are thoroughly tested with this version. If you are using a different version of Java, see Java compatibility notes for more information on possible additional configuration or deployment steps.

## Azul Zulu 11

Azul Zulu is a free, open-source OpenJDK distribution compatible with Java SE and available across Windows, Linux, and macOS. It serves as a direct replacement for Oracle JDK, ideal for production environments without licensing fees. Azul Zulu also provides LTS versions for Java 8, 11, and 17, allowing you to select a secure, stable version and avoid frequent upgrades to new major versions.

To install Azul Zulu 11 on a Debian-flavored distribution, you can use the following commands:

sudo apt install -y gnupg ca-certificates curl
curl -s https://repos.azul.com/azul-repo.key | sudo gpg --dearmor -o /usr/share/keyrings/azul.gpg
echo "deb [signed-by=/usr/share/keyrings/azul.gpg] https://repos.azul.com/zulu/deb stable main" | sudo tee /etc/apt/sources.list.d/zulu.list

Then, run the following command to install the Azul Zulu 11 JDK:

sudo apt update
sudo apt install -y zulu11-jdk

For additional operating systems, see the Azul Zulu Installation Packages. To view the LTS Roadmap, see the Azul Zulu Roadmap.

Amazon Corretto is an additional option for LTS Java support, and is available for free from Amazon with a similar setup procedure.

# CouchDB

Apache CouchDB is a NoSQL database that is used to store and manage data in Spaceport. It is a document-oriented database that allows for a robust and flexible data model, as well as fault tolerance and replication. While CouchDB is required by Spaceport for data storage, working with CouchDB directly is not required for most applications. Spaceport offers a Document API that streamlines the process of storing Documents in CouchDB, and the Spaceport CLI offers a command-line interface for managing your CouchDB instance, as well.

## Installing CouchDB

CouchDB is available for most operating systems, and can be installed using your package manager, or by visiting the CouchDB Downloads Page.

If you are using a Debian-flavored Linux distribution, you can easily install and setup CouchDB using the official repository.

sudo apt update && sudo apt install -y curl apt-transport-https gnupg
curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null 2>&1
source /etc/os-release
echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ ${VERSION_CODENAME} main" \
    | sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null

Then, run the following command to install CouchDB:

sudo apt update
sudo apt install -y couchdb

This installation process will prompt you to configure CouchDB. You can choose to configure it as a standalone server or a clustered server. For most projects the standalone server option is sufficient. When prompted for the address, use 127.0.0.1 on Linux or localhost on Windows. The connection Spaceport uses to connect to CouchDB is on the backend and, in most cases, should not be exposed to the public internet. Also, note the password for the admin user, as you will need it to configure Spaceport's connection to CouchDB.

## The CouchDB Fauxton Web Interface

CouchDB includes a web interface called Fauxton, which allows you to manage your CouchDB instance and view databases and documents. You can access Fauxton by navigating to http://localhost:5984/_utils/ in your web browser. You will be prompted to enter your CouchDB admin username and password. Once logged in, you can create databases, view documents, and manage your CouchDB instance. This interface is not required for normal operation, but it can be useful when debugging issues with document storage or if you need to manually manipulate your database.

Note: If you are using a different operating system, see the CouchDB Installation Instructions for more information.

# Code Editor

Spaceport dynamically loads Groovy Source Modules and other resources from the filesystem without a traditional build process. This means you can use any text editor or IDE to edit your Groovy files, and Spaceport will automatically reload them when you save your changes. This allows for rapid development and iteration without the need for a complex build process. While you can use nano, vim, or any other text editor, using a more advanced editor or IDE can significantly improve your productivity and development experience, especially as a beginner. Here are some recommended options with syntax highlighting support for Groovy and Launchpad Template (.ghtml) files.

## Sublime Text

Sublime Text is a popular text editor available for Windows, macOS, and Linux. It is powerful and flexible, supporting a wide range of programming languages and file types. It is also highly customizable, allowing you to install plugins and themes to enhance your development experience. Sublime Text is a great choice for Spaceport, and Spaceport offers a Sublime Text plugin that provides syntax highlighting for Groovy files and Launchpad Template (.ghtml) files.

### Installing Sublime Text

Sublime Text is available for most operating systems and can be installed using your package manager or by visiting the Sublime Text Downloads Page.

If you are using a Debian-flavored Linux distribution, you can easily install and set up Sublime Text using the official repository.

sudo apt update && sudo apt install -y wget apt-transport-https gnupg
wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | sudo tee /etc/apt/keyrings/sublimehq-pub.asc > /dev/null
echo -e 'Types: deb\nURIs: https://download.sublimetext.com/\nSuites: apt/stable/\nSigned-By: /etc/apt/keyrings/sublimehq-pub.asc' | sudo tee /etc/apt/sources.list.d/sublime-text.sources

Then, run the following command to install Sublime Text:

sudo apt update
sudo apt install -y sublime-text

Restart your terminal, and you can launch Sublime Text by running the subl command.

## JetBrains IntelliJ IDEA

JetBrains IntelliJ IDEA is a powerful IDE available for Windows, macOS, and Linux. It is designed for Java development, but it also supports a wide range of programming languages and file types, including Groovy. IntelliJ IDEA is highly customizable, allowing you to install plugins and themes to enhance your development experience. IntelliJ IDEA is a great choice for Spaceport, and the Ultimate edition offers additional features for front-end development, such as HTML, CSS, and JavaScript support.

IDEA Ultimate is the recommended edition for Spaceport development, but be aware that it is a paid product. If you are looking for a free option, the Community edition is available, but it lacks some front-end syntax highlighting and other features that may be useful when developing Spaceport applications full-stack. It still has a robust set of features for Groovy development, including code completion, refactoring, and debugging. Ultimate is available for free to students and open-source projects, and it also has a free 30-day trial.

### Installing IntelliJ IDEA

IntelliJ IDEA is available for most operating systems and can be installed using your package manager or by visiting the IntelliJ IDEA Downloads Page.

### Installing the Grails Plugin

Spaceport leverages some concepts from the Grails web framework, and the Grails plugin for IntelliJ IDEA provides additional support to Spaceport's .ghtml Launchpad Template files. To install the Grails plugin, follow these steps:

Note: Associating .ghtml files as Groovy Server Pages (provided by the Grails plugin) is not a perfect solution, but while tooling is being developed specifically for Spaceport it provides a reasonable compromise for syntax highlighting and basic editing features that are better than nothing.

### Using with Gateway

Jetbrains Gateway is a backend IDE with a frontend wrapper that allows you to connect to a remote development environment, and it works well with remote Spaceport development. To use Gateway on a Spaceport project, just enable SSH access to your remote server, and install the Jetbrains Gateway application on your local machine. Then, follow these steps:

Any changes you make will be saved directly to the remote server.

# Conclusion

You're now equipped with the platform prerequisites and tooling choices to be productive in Spaceport. The development loop is intentionally tight: Launch your Spaceport server with debug enabled, edit your Groovy source modules or Launchpad template source, save, and immediately observe results without rebuilds. This rapid feedback loop encourages experimentation and iteration, allowing you to focus on building your application without being bogged down by complex build processes or tooling.

## Quick Checklist to Start

# Next Steps

Recommended next reads:

If you prefer a hands-on path, start with the Tic-Tac-Toe Tutorial or the Meeting Room Tutorial—or explore one of these starting points and example applications: