Installation

This guide covers how to install and set up Kinesis API on your system. We offer two installation methods: Docker (recommended for most users) and direct Rust installation (useful for developers contributing to the project).

System Requirements

Before installing Kinesis API, ensure your system meets these minimum requirements:

• Memory: 128MB RAM minimum (512MB+ recommended for production use)
• CPU: 1 core minimum (2+ cores recommended for production)
• Storage: 100MB for installation + additional space for your data
• Operating System: Any OS that can run Docker or Rust (Linux, macOS, Windows)
• Network: Outbound internet access for installation

Configuration Options

Before installing Kinesis API, you should decide on your configuration settings. These can be set through environment variables.

Essential Environment Variables

Database Configuration

You can configure the database system through additional environment variables:

Important: Changing database-related environment variables after your initial setup may cause data access issues or corruption. It's best to decide on these settings before your first initialization and maintain them throughout the lifecycle of your installation.

Docker Installation (Recommended)

Using Docker is the simplest and most reliable way to deploy Kinesis API.

Prerequisites

1. Install Docker on your system
2. Ensure you have permissions to create and manage Docker containers

Installation Steps

1. Create necessary directories for persistent storage:

mkdir -p data/ public/

2. Create a .env file with your configuration:

echo "TMP_PASSWORD=yourSecurePassword" > .env
echo "API_URL=http://your-domain-or-ip:8080" >> .env

Replace yourSecurePassword with a strong password and your-domain-or-ip with your server's domain or IP address.

3. Add any additional configuration options from the Configuration Options section above to your .env file.

4. Run the Docker container:

docker run --name kinesis-api \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/public:/app/public \
  -p 8080:8080 -d \
  --restart unless-stopped \
  edgeking8100/kinesis-api:latest

This command:

• Names the container kinesis-api
• Mounts your local .env file and data/public directories
• Exposes port 8080
• Runs in detached mode (-d)
• Configures automatic restart
• Uses the latest Kinesis API image

Using a Specific Version

If you need a specific version of Kinesis API, replace latest with a version number:

docker run --name kinesis-api \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/public:/app/public \
  -p 8080:8080 -d \
  --restart unless-stopped \
  edgeking8100/kinesis-api:0.25.0

Available Registries

Kinesis API images are available from multiple registries:

Rust Installation (For Development)

If you're a developer who wants to build from source or contribute to Kinesis API, you can install using Rust.

Prerequisites

1. Install Rust (version 1.86 or newer)
2. Install development tools for your platform:
   • Linux: build-essential package or equivalent
   • macOS: Xcode Command Line Tools
   • Windows: Microsoft Visual C++ Build Tools

Installation Steps

1. Clone the repository:

git clone https://gitea.konnect.dev/rust/kinesis-api.git
cd kinesis-api/

2. Create and configure the environment file:

cp .env.template .env

3. Edit the .env file to set at minimum:

   • TMP_PASSWORD with a secure value
   • API_URL with your server address (e.g., "http://localhost:8080")

4. Build and run the application:

cargo run --bin kinesis-api

For a production build:

cargo build --release --bin kinesis-api
./target/release/kinesis-api

Post-Installation Steps

After installation, you need to initialize Kinesis API:

1. Access the initialization endpoint:

   • Make a GET request to <your-api-url>/init?code=code, or
   • Navigate to the web interface at <your-api-url>/web

2. This creates a root user with:

   • Username: root
   • Password: Test123*

3. Important: Change the default password immediately after first login

For more details on initialization, see the Initialization Guide.

Verifying the Installation

To confirm Kinesis API is running correctly:

1. Open your browser and navigate to <your-api-url>/web
2. You should see the Kinesis API login page
3. Try logging in with the default credentials
4. Check that you can access the API documentation at <your-api-url>/scalar

Troubleshooting

Common Issues

1. Container won't start:

   • Check Docker logs: docker logs kinesis-api
   • Ensure ports aren't already in use
   • Verify directory permissions

2. Can't access the web interface:

   • Confirm the container is running: docker ps
   • Check your firewall settings
   • Verify the URL and port configuration

3. Database connection errors:

   • Check the data directory permissions
   • Verify your DB configuration variables

Getting Help

If you encounter issues not covered here:

• Check our FAQ page
• Contact support at support@kinesis.world
• Submit a detailed bug report through our issue tracker

Next Steps

After installation, proceed to:

1. Initialize your installation
2. Configure your setup
3. Build a Simple Counter App