← URL Shortener

Getting started

From a fresh clone to your first redirect in a few minutes — build the modules, start the server, create a short link, then add the admin UI and durable storage when you need them.

The path from clone to first redirect

The whole journey at a glance. Each step has its exact commands further down the page.

1. Clone the repository Pull the source and enter the project directory.
2. Build all modules Build the four Maven modules in one pass.
3. Start the server Launch the server jar — the Admin API on 9090 and public redirects on 8081.
4. Create your first short link POST a URL and a custom alias to the Admin API.
5. Use the short link Follow the short code and get a 302 redirect to the original URL.
6. Vaadin admin UI — optional Deploy the WAR to Jetty 12 for a browser-based administration surface.
7. Persistence — optional Switch from in-memory to EclipseStore for durable, restart-surviving storage.

Prerequisites

Build and run

Clone the repository, build the four Maven modules, and start the server.

Clone the repository

git clone https://github.com/svenruppert/url-shortener.git
cd url-shortener

Build all modules

mvn clean package -DskipTests

This builds four modules, in order:

Start the server

cd urlshortener-server
java -jar target/urlshortener-server-*.jar

The server starts two listeners:

Create your first short link

Create a short link

curl -X POST http://localhost:9090/api/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://github.com/svenruppert/url-shortener",
    "alias": "oss-project"
  }'

Response:

{
  "shortCode": "oss-project",
  "originalUrl": "https://github.com/svenruppert/url-shortener",
  "active": true,
  "createdAt": "2025-01-01T12:00:00Z"
}

Use the short link

curl -L http://localhost:8081/oss-project
# → 302 redirect to https://github.com/svenruppert/url-shortener

Vaadin admin UI

Deploy the WAR to a Jetty 12 server:

cp urlshortener-ui/target/ROOT-*.war /path/to/jetty/webapps/ROOT.war
cd /path/to/jetty && java -jar start.jar

Open http://localhost:8080 in your browser.

Persistence

To enable persistent storage with EclipseStore, set the system property:

java -Dstorage.mode=eclipsestore \
     -Dstorage.path=/var/urlshortener/data \
     -jar target/urlshortener-server-*.jar

Next steps