Marstech - Link Spray

Marstech - Link Spray is a web application that allows you to open multiple URLs with a single click. Follow a few simple steps to generate a unique link that will open all the specified URLs.

Badges

Features

• Link Spray: Enter multiple URLs and generate a single link to open them all at once.
• URL Shortener: Shorten long URLs and resolve short codes back to their original targets.
• Paste Service: Create, retrieve, and password-protect text pastes with syntax highlighting support.
• Dashboard: Manage collections of links and pastes via a personal dashboard.
• Abuse Reporting: Report abusive or malicious links directly from the interface.
• Random Number Generator: Generate random numbers within a configurable range via API.
• UUID Generator: Generate random UUIDs via API.
• Random ID Cache: Pre-generated ID cache for high-throughput short link creation.
• Mail Notifications: Email notification support via configurable SMTP settings.
• Actuator: Health check and endpoint mapping exposed via Spring Actuator.

Technologies used

Technology	Version
Kotlin	2.3.21
Java	21 (Temurin)
Spring Boot	3.5.14
Spring WebMVC	(via Boot)
Spring Data MongoDB	(via Boot)
Spring Security Crypto	(via Boot)
Spring Boot Actuator	(via Boot)
Thymeleaf	(via Boot)
Bootstrap	(frontend)
Maven	Build tool
MongoDB	Database
Docker	Dev/test
JUnit 5 / Mockito	Testing
Flapdoodle Embed Mongo	4.21.0 (tests)
Apache Commons Lang3	3.20.0
Apache Commons Collections4	4.4
Jackson Kotlin Module	2.20.0
Kotlinx Coroutines	1.10.2
JReleaser	Releases

Project Structure

src/main/kotlin/fr/marstech/mtlinkspray/
├── conf/           # Configuration classes and event handlers
├── controller/
│   ├── api/        # REST API endpoints
│   │   ├── DashboardApiController.kt
│   │   ├── PasteApiController.kt
│   │   ├── RandomNumberApiController.kt
│   │   ├── RootApiController.kt
│   │   ├── ShortenerApiController.kt
│   │   ├── SprayApiController.kt
│   │   └── UuidApiController.kt
│   └── view/       # Thymeleaf view controllers
│       ├── DashboardViewController.kt
│       ├── PasteViewController.kt
│       ├── UrlRedirectController.kt
│       ├── ViewAbuseController.kt
│       ├── ViewRootController.kt
│       ├── ViewShortenerController.kt
│       ├── ViewSprayController.kt
│       └── ViewUuidController.kt
├── dto/            # Data Transfer Objects
├── entity/         # MongoDB document entities
├── enums/          # Enumerations
├── exception/      # Custom exceptions
├── objects/        # Shared objects and constants
├── repository/     # Spring Data MongoDB repositories
├── service/        # Business logic interfaces and implementations
├── utils/          # Utility classes
└── validation/     # Custom validation annotations and validators

API Endpoints

Method	Path	Description
GET	/api/version	Returns current application version
GET	/api/spray	Generate a Link Spray URL
GET	/api/url-shortener/shorten	Shorten a URL
GET	/api/paste/{pasteId}	Retrieve a paste
POST	/api/paste	Create a new paste
GET	/api/dashboard/{id}	Get a dashboard by ID
POST	/api/dashboard	Create a new dashboard
PUT	/api/dashboard/{id}	Update an existing dashboard
GET	/api/random	Generate a random number
GET	/api/uuid	Generate a random UUID
POST	/api/md2pdf	Markdown body to PDF (X-Api-Key)
POST	/api/pdf2md	PDF body to Markdown (X-Api-Key)
GET	/{shortUrlUid}	Redirect to the target URL

SDK Version Management

This project uses SDKMan to manage SDK versions consistently across environments. A .sdkmanrc file at the project root pins the exact versions used:

java=21.0.11-tem
maven=3.9.15
kotlin=2.3.21
springboot=3.5.14

Enable automatic SDK switching

1. Install SDKMan if not already installed:

   curl -s "https://get.sdkman.io" | bash
   source "$HOME/.sdkman/bin/sdkman-init.sh"
   

2. Enable auto-env switching in ~/.sdkman/etc/config:

   sdkman_auto_env=true
   

3. SDKMan will automatically switch to the correct SDK versions when entering the project directory:

   cd marstech-link-spray
   # SDKMan applies .sdkmanrc automatically
   java -version  # Should show Java 21 (Temurin)
   

4. To apply manually without auto-env:

   sdk env install  # Install all versions declared in .sdkmanrc
   sdk env          # Apply versions for current session
   

See docs/setup-guide.md for full environment setup instructions.

Installation

1. Clone the repository:

   git clone https://github.com/alkaphreak/marstech-link-spray.git
   

2. Configure MongoDB:

   • Ensure that MongoDB is installed and running on your machine or set up a MongoDB instance using Docker, or on a cloud platform, a MongoDB Atlas free tier is available.
   • Set the MONGODB_URI_LINK_SPRAY environment variable with the connection URI to your MongoDB database. For example:

     # On Linux/macOS, in ~/.profile or ~/.bash_profile or ...
     export MONGODB_URI_LINK_SPRAY="mongodb://localhost:27017/mydatabase"
     

   • Reload your shell configuration file (e.g., ~/.profile or ~/.bash_profile):

     source ~/.profile
     

   • You can also need this command to avoid restarting your Mac:

     launchctl setenv MONGODB_URI_LINK_SPRAY "$MONGODB_URI_LINK_SPRAY"
     

   • Alternatively, you can set the MONGODB_URI_LINK_SPRAY property in the application.properties file.
   • You may be forced to restart your IDE to take into account the new environment variable.

3. Build and run the application:

   mvn clean install
   mvn spring-boot:run
   

4. Access the application in your browser, by default at:

   http://localhost:8096
   

Configuration

The application can be configured through the application.properties file or environment variables.

Property / Variable	Description	Default
MONGODB_URI_LINK_SPRAY	MongoDB connection URI (prod profile)	-
LINK_SPRAY_ADMIN_USERNAME	Admin Basic-auth user (required)	-
LINK_SPRAY_ADMIN_PASSWORD	Admin Basic-auth password (required)	-
LINK_SPRAY_DO_SPACES_ENDPOINT	DO Spaces endpoint (required)	-
LINK_SPRAY_DO_SPACES_ACCESS_KEY	DO Spaces access key (required)	-
LINK_SPRAY_DO_SPACES_SECRET_KEY	DO Spaces secret key (required)	-
LINK_SPRAY_DO_SPACES_REGION	DO Spaces region	tor1
LINK_SPRAY_DO_SPACES_BUCKET	DO Spaces bucket for images	mt-mls-img-storage
server.port	HTTP server port	8096
mt.link-spray.protocol	Public protocol (http/https)	http
mt.link-spray.host	Public hostname	localhost
mt.link-spray.port	Public port	${server.port}
mt.link-spray.random-id.charset	Character set for random ID generation	alphanumeric
mt.link-spray.random-id.length	Length of generated short IDs	5
mt.link-spray.random-id.cache.enabled	Enable pre-generated ID cache	true
mt.link-spray.random-id.cache.depth	Number of IDs to pre-generate in cache	100
mt.link-spray.random-id.cache.treshold	Threshold to trigger cache refill	10
LINK_SPRAY_SMTP_HOST	SMTP server host

Spring Profiles

Profile	MongoDB URI	Notes
dev	localhost:27017	Local development
test	localhost:27018 (embedded)	Integration tests
prod	${MONGODB_URI_LINK_SPRAY}	Production (env variable)

Usage

1. Enter the URLs you want to open, one per line, in the text field.
2. Click the "Generate URL" button.
3. Use the generated link to open all the URLs with a single click.

Performance

A simple test to retrieve 10 000 ids with and without the cache.

• With cache: 473ms
• Without cache: 11 327 ms
• Difference: 10 854 ms
• Test range: 10 000
• Cache depth: 100
• Cache treshold: 10

Test containers

If you experience a message like this:

Reuse was requested, but the environment does not support the reuse of containers To enable reuse of containers, you must set 'testcontainers.reuse.enable=true' in a file located at $ HOME/.testcontainers.properties

Run this in shell or do it manually:

echo "testcontainers.reuse.enable=true" >> $HOME/.testcontainers.properties

Releases

This project uses JReleaser for automated, professional releases. Current version: 0.2.0

Quick Release

1. Go to GitHub Actions → "Release" workflow
2. Click "Run workflow" and select bump type (patch, minor, or major)
3. Automated release with changelog and artifacts

See RELEASE.md for detailed release documentation.

Docker

The application is available as a multi-arch Docker image (linux/amd64, linux/arm64) on Docker Hub.

• Docker Hub repository: https://hub.docker.com/r/alkaphreak/marstech-link-spray
• All tags and versions: https://hub.docker.com/r/alkaphreak/marstech-link-spray/tags

Pull and run

# Pull latest
docker pull alkaphreak/marstech-link-spray:latest

# Pull a specific version
docker pull alkaphreak/marstech-link-spray:v0.2.0

# Run (replace with your MongoDB URI)
docker run -d \
  --name marstech-link-spray \
  --restart unless-stopped \
  -p 8096:8096 \
  -e MONGODB_URI_LINK_SPRAY="mongodb://your-mongo-host:27017/linkspray" \
  alkaphreak/marstech-link-spray:latest

Contributing

Contributions are welcome! To contribute:

1. Fork the project.
2. Create a branch for your feature (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push your branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Authors

• Stéphane ROBIN - Creator - Link

---

\© 2024 Marstech. All rights reserved.

---

Hi there

Here is my Linktree: https://linktr.ee/StephaneRobinJob

Here is my referral link on DigitalOcean: https://m.do.co/c/be389fc15e1a

Get $200 in free DigitalOcean credits to deploy your next project! Perfect for developers starting their cloud journey.