Configuration overview DZDK stores its configuration in a YAML file located at:
Linux/macOS : ~/.config/dzdk/config.yamlWindows : %USERPROFILE%\.config\dzdk\config.yaml
The configuration file is automatically created with default values on first run.
Default configuration When DZDK is first installed, it creates a configuration file with these defaults:
api_url : https://services.dzaleka.com/api timeout : 30
Configuration options API URL The base URL for the Dzaleka Digital Heritage API.
Key : api_urlType : StringDefault : https://services.dzaleka.com/apiExample : https://services.dzaleka.com/api
The API URL is automatically formatted to ensure it starts with https:// and ends with /api.
Request timeout Maximum time (in seconds) to wait for API responses before timing out.
Key : timeoutType : IntegerDefault : 30Range : 1-300 secondsExample : 30
Setting a very low timeout (< 5 seconds) may cause requests to fail on slower connections.
Viewing configuration Show current settings Display your current DZDK configuration:
This command displays:
╭─────────────────────────────────────────╮ │ Current Configuration │ │ Your CLI settings │ ╰─────────────────────────────────────────╯ ╭─────────────────────────────────────────╮ │ Configuration Details │ ├─────────────────────────────────────────┤ │ API Settings │ │ URL: https://services.dzaleka.com/api │ │ Timeout: 30 seconds │ │ │ │ Configuration File │ │ Location: /home/user/.config/dzdk/config.yaml │ Last Modified: 2024-03-20 14:30:15 │ ╰─────────────────────────────────────────╯
You can also use dzdk show_config (with underscore) as an alias.
Updating configuration Interactive mode Use interactive mode for a guided configuration experience:
dzdk config --interactive
This will:
Show your current configuration
Prompt you for the API URL (with current value as default)
Prompt you for the timeout (with current value as default)
Save the updated configuration
Display a confirmation message
Example session:
╭─────────────────────────────────────────╮ │ Interactive Configuration │ │ Configure your CLI settings │ ╰─────────────────────────────────────────╯ ╭─────────────────────────────────────────╮ │ Current Configuration │ ├─────────────────────────────────────────┤ │ API URL: https://services.dzaleka.com/api │ Timeout: 30 seconds │ ╰─────────────────────────────────────────╯ Enter API URL [https://services.dzaleka.com/api]: https://api.example.com Enter timeout in seconds [30]: 60 ╭─────────────────────────────────────────╮ │ Configuration Updated │ ├─────────────────────────────────────────┤ │ Configuration has been updated successfully! │ │ │ New Settings: │ │ API URL: https://api.example.com/api │ │ Timeout: 60 seconds │ ╰─────────────────────────────────────────╯
Command-line options Update specific settings using command-line flags:
Set API URL
Set timeout
Set both
dzdk config --url "https://services.dzaleka.com/api"
When setting the API URL via command line, DZDK automatically ensures it ends with /api.
Manual editing You can also edit the configuration file directly:
Locate the config file
# Linux/macOS nano ~/.config/dzdk/config.yaml # Windows notepad %USERPROFILE% \. config \d zdk \c onfig.yaml
Edit the values
api_url : https://services.dzaleka.com/api timeout : 30
Environment variables Custom config directory Override the default configuration directory location:
export DZDK_CONFIG_DIR = "/path/to/custom/config"
Example:
# Set custom directory export DZDK_CONFIG_DIR = " $HOME /my-dzdk-config" # DZDK will now use this directory dzdk show-config
The config file will be created at $DZDK_CONFIG_DIR/config.yaml.
Persistent environment variable Make the environment variable permanent:
Linux/macOS (bash)
Linux/macOS (zsh)
Windows (PowerShell)
# Add to ~/.bashrc or ~/.bash_profile echo 'export DZDK_CONFIG_DIR="$HOME/my-dzdk-config"' >> ~/.bashrc source ~/.bashrc
Configuration file structure The configuration file uses YAML format. Here’s the complete structure:
# API Configuration api_url : https://services.dzaleka.com/api # Base API URL timeout : 30 # Request timeout in seconds
DZDK automatically normalizes the API URL:
Ensures it starts with https:// (adds if missing)
Ensures it ends with /api (appends if missing)
Removes trailing slashes before adding /api
Examples of automatic formatting:
Input Normalized Output services.dzaleka.comhttps://services.dzaleka.com/apihttps://services.dzaleka.comhttps://services.dzaleka.com/apihttps://services.dzaleka.com/https://services.dzaleka.com/apihttps://services.dzaleka.com/apihttps://services.dzaleka.com/apihttps://services.dzaleka.com/api/https://services.dzaleka.com/api
Configuration validation DZDK automatically validates configuration values:
API URL validation
Must be a valid URL format
Automatically adds https:// if protocol is missing
Automatically adds /api suffix if missing
Timeout validation
Must be a positive integer
Recommended range: 5-300 seconds
Default is 30 seconds if invalid value provided
Testing configuration After updating your configuration, verify it works:
# Check API connectivity dzdk health
This command will:
Use your configured API URL
Apply your configured timeout
Test all API endpoints
Display response times and status
Successful output:
╭─────────────────────────────────────────╮ │ API Health Check │ │ Monitoring all endpoints │ ╰─────────────────────────────────────────╯ ┌────────────┬────────┬───────────────┬─────────┐ │ Endpoint │ Status │ Response Time │ Details │ ├────────────┼────────┼───────────────┼─────────┤ │ services │ ✓ │ 0.23s │ OK │ │ events │ ✓ │ 0.18s │ OK │ │ photos │ ✓ │ 0.21s │ OK │ │ population │ ✓ │ 0.19s │ OK │ │ resources │ ✓ │ 0.24s │ OK │ └────────────┴────────┴───────────────┴─────────┘ ✓ All endpoints are healthy
Troubleshooting Configuration file not found If the configuration file doesn’t exist:
# Run any DZDK command to auto-create it dzdk show-config
DZDK will automatically create the configuration directory and file with default values.
Invalid configuration values If you manually edit the config file and introduce errors:
# Reset to defaults rm ~/.config/dzdk/config.yaml # Linux/macOS dzdk show-config # Recreates with defaults
Connection failures If the health check fails after configuration:
Verify API URL
Ensure the API URL is correct.
Test connectivity
curl https://services.dzaleka.com/api/health
Verify you can reach the API directly.
Increase timeout
Try a longer timeout for slow connections.
Check network
Ensure you have internet connectivity and the API server is running.
Permission errors If you get permission errors accessing the config file:
# Fix permissions (Linux/macOS) chmod 600 ~/.config/dzdk/config.yaml # Or recreate the config directory rm -rf ~/.config/dzdk dzdk show-config
Advanced configuration Multiple environments Manage different configurations for different environments:
# Production config export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-prod" dzdk config --url "https://services.dzaleka.com/api" # Development config export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-dev" dzdk config --url "http://localhost:8000/api" # Switch between them as needed export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-prod" dzdk health
Shell aliases Create aliases for different environments:
# Add to your shell configuration file alias dzdk-prod = 'DZDK_CONFIG_DIR="$HOME/.config/dzdk-prod" dzdk' alias dzdk-dev = 'DZDK_CONFIG_DIR="$HOME/.config/dzdk-dev" dzdk' # Usage dzdk-prod health dzdk-dev health
Backup and restore Backup your configuration:
# Backup cp ~/.config/dzdk/config.yaml ~/dzdk-config-backup.yaml # Restore cp ~/dzdk-config-backup.yaml ~/.config/dzdk/config.yaml
Configuration best practices Keep timeouts reasonable : Set timeout between 10-60 seconds. Too short causes failures, too long causes hanging.
Use environment variables for CI/CD : In automated environments, use DZDK_CONFIG_DIR to avoid conflicts.
Version control : If managing multiple configurations, keep them in version control but exclude sensitive data.
Security : The configuration file doesn’t currently store credentials, but if extended in the future, ensure proper file permissions (600 on Unix systems).
Next steps