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
Variable | Description | Example |
---|---|---|
TMP_PASSWORD | Temporary password for setup | StrongPassword123! |
API_URL | URL where Kinesis API will be accessed | http://localhost:8080 |
Database Configuration
You can configure the database system through additional environment variables:
Variable | Description | Possible Values | Default |
---|---|---|---|
DB_NAME | Database filename | Any valid filename | main_db |
DB_STORAGE_ENGINE | Storage engine type | memory , disk , hybrid | hybrid |
DB_ISOLATION_LEVEL | Transaction isolation level | read_uncommitted , read_committed , repeatable_read , serializable | serializable |
DB_BUFFER_POOL_SIZE | Buffer pool size | Any positive integer | 100 |
DB_AUTO_COMPACT | Automatic compaction | true , false | true |
DB_RESTORE_POLICY | Recovery policy | discard , recover_pending , recover_all | recover_pending |
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
- Install Docker on your system
- Ensure you have permissions to create and manage Docker containers
Installation Steps
- Create necessary directories for persistent storage:
mkdir -p data/ public/
- 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.
-
Add any additional configuration options from the Configuration Options section above to your
.env
file. -
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:
Registry | Image |
---|---|
Docker Hub | docker.io/edgeking8100/kinesis-api:latest |
Docker Hub | docker.io/edgeking8100/kinesis-api:<version> |
Gitea Registry | gitea.konnect.dev/rust/kinesis-api:latest |
Gitea Registry | gitea.konnect.dev/rust/kinesis-api:<version> |
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
- Install Rust (version 1.86 or newer)
- Install development tools for your platform:
- Linux:
build-essential
package or equivalent - macOS: Xcode Command Line Tools
- Windows: Microsoft Visual C++ Build Tools
- Linux:
Installation Steps
- Clone the repository:
git clone https://gitea.konnect.dev/rust/kinesis-api.git
cd kinesis-api/
- Create and configure the environment file:
cp .env.template .env
-
Edit the
.env
file to set at minimum:TMP_PASSWORD
with a secure valueAPI_URL
with your server address (e.g., "http://localhost:8080")
-
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:
-
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
- Make a GET request to
-
This creates a root user with:
- Username:
root
- Password:
Test123*
- Username:
-
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:
- Open your browser and navigate to
<your-api-url>/web
- You should see the Kinesis API login page
- Try logging in with the default credentials
- Check that you can access the API documentation at
<your-api-url>/scalar
Troubleshooting
Common Issues
-
Container won't start:
- Check Docker logs:
docker logs kinesis-api
- Ensure ports aren't already in use
- Verify directory permissions
- Check Docker logs:
-
Can't access the web interface:
- Confirm the container is running:
docker ps
- Check your firewall settings
- Verify the URL and port configuration
- Confirm the container is running:
-
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: