Skip to main content
This guide covers the complete installation process for JSIFEN, including system requirements, dependencies, and configuration.

​
System Requirements

JSIFEN requires the following to run:

Java

Version: Java 17 or higherRecommended: Java 21 LTS

Operating System

Linux, macOS, or WindowsAll major platforms supported

Certificate

PKCS12 (.p12) certificateRequired for SIFEN authentication

Network Port

Port 8000 (default)Configurable in settings

​
Installation Steps

1
Install Java
2
Ensure you have Java 17 or higher installed. Verify your installation:
3
java -version
4
You should see output indicating Java 17 or higher:
5
openjdk version "21.0.1" 2023-10-17 LTS
6
We recommend using SDKMAN! on Linux/macOS or Adoptium on Windows to manage Java installations.
7
Clone the repository
8
Clone JSIFEN from your Git repository:
9
git clone https://github.com/your-org/jsifen.git
cd jsifen
10
Configure application properties
11
JSIFEN uses two main configuration files located in src/main/resources/:
12
application.properties
13
Configure the HTTP port and API documentation path:
14
# HTTP server port
quarkus.http.port=8000

# Swagger UI documentation path
quarkus.swagger-ui.path=/doc/swagger
15
sifen.properties
16
Configure your SIFEN credentials and certificate:
17
# SIFEN Environment (prod/test)
sifen.ambiente=prod
sifen.id-csc=0001
sifen.csc=your-csc-code-here
sifen.keystore.path=/path/to/certificate.p12
sifen.keystore.password=your-certificate-password
18
Never commit credentials to version control. Consider using environment variables or secure vaults for production deployments.
19
Build the application
20
Build JSIFEN using Gradle:
21
Linux/macOS
./gradlew build
Windows
gradlew.bat build
22
The build process will:
23
  • Compile all Java source files
  • Run tests
  • Create a runnable JAR in build/quarkus-app/
  • Copy configuration files to build/quarkus-app/config/
    • 24
    The build process is configured to automatically copy application.properties and sifen.properties to the output directory’s config/ folder.
    25
    Verify the installation
    26
    Run the application to verify everything is set up correctly:
    27
    Development Mode
    ./gradlew quarkusDev
    Production Mode
    cd build/quarkus-app
java -Dquarkus.config.locations=./config -jar quarkus-run.jar

    ​
    Build Output Structure

    After building, your application structure will be: 
    build/quarkus-app/
├── quarkus-run.jar          # Main executable
├── config/
│   ├── application.properties
│   └── sifen.properties
├── lib/                      # Dependencies
└── quarkus/                  # Quarkus runtime files

    ​
    Configuration Details

    ​
    Port Configuration

    The default port is 8000. To change it, edit src/main/resources/application.properties: 
    quarkus.http.port=8080
    Or override at runtime: 
    java -Dquarkus.http.port=8080 -jar quarkus-run.jar

    ​
    Multi-Tenant Configuration

    JSIFEN supports multiple SIFEN clients (emisores). Add additional configurations in sifen.properties: 
    # Default client
sifen.ambiente=prod
sifen.id-csc=0001
sifen.csc=default-csc-code
sifen.keystore.path=/path/to/default-cert.p12
sifen.keystore.password=default-password

# Additional client (e.g., "sanantonio")
sifen.sanantonio.ambiente=prod
sifen.sanantonio.id-csc=0002
sifen.sanantonio.csc=sanantonio-csc-code
sifen.sanantonio.keystore.path=/path/to/sanantonio-cert.p12
sifen.sanantonio.keystore.password=sanantonio-password
    Then specify the client using the Emisor header in API requests: 
    curl -X POST http://localhost:8000/consulta/ruc \
  -H "Content-Type: application/json" \
  -H "Emisor: sanantonio" \
  -d '{"ruc": "80012345-6"}'

    ​
    Testing the Installation

    Run the test suite to ensure everything is working: 
    ./gradlew test
    Test the health endpoint: 
    curl http://localhost:8000/health/sifen/test
    Expected response: 
    {
  "status": "UP",
  "timestamp": "2026-03-08T10:30:00Z"
}

    ​
    Dependencies

    JSIFEN is built on the following key technologies:
    • Quarkus 3.26.2: Kubernetes-native Java framework
    • Java 21: Target compilation version
    • Jakarta EE: REST, JSON-B APIs
    • SmallRye OpenAPI: API documentation generation
    All dependencies are managed automatically by Gradle.

    ​
    Troubleshooting

    ​
    Build Failures

    Issue: Gradle build fails with compilation errors Solution: Ensure you’re using Java 17 or higher: 
    java -version

    ​
    Certificate Errors

    Issue: Certificate not found or invalid password Solution:
    • Verify the certificate path is absolute, not relative
    • Check the certificate password is correct
    • Ensure the certificate file has proper read permissions

    ​
    Port Conflicts

    Issue: Port 8000 is already in use Solution: Change the port in application.properties or use a runtime override: 
    java -Dquarkus.http.port=8080 -jar quarkus-run.jar

    ​
    SIFEN Connection Issues

    Issue: Cannot connect to SIFEN services Solution:
    • Verify your credentials are correct
    • Check network connectivity to SIFEN servers
    • Ensure you’re using the correct environment (test or prod)
    • Verify your certificate is valid and not expired

    ​
    Next Steps

    Quickstart

    Make your first API call in under 10 minutes

    Configuration

    Learn about advanced configuration options

    API Reference

    Explore all available endpoints

    Deployment

    Deploy JSIFEN to production

    Build docs developers (and LLMs) love

    Get started for freeTalk to us