From c97a3f07a7d58bc504d3fe0a0ad98adc3818afee Mon Sep 17 00:00:00 2001 From: Maidul Islam Date: Thu, 24 Apr 2025 14:10:21 -0700 Subject: [PATCH] update linux docs --- docs/mint.json | 1 - .../linux-package/commands-configuration.mdx | 40 ++--- .../native/linux-package/installation.mdx | 164 ++++++++++-------- .../native/linux-package/migration.mdx | 30 ---- docs/self-hosting/overview.mdx | 3 +- 5 files changed, 114 insertions(+), 124 deletions(-) delete mode 100644 docs/self-hosting/deployment-options/native/linux-package/migration.mdx diff --git a/docs/mint.json b/docs/mint.json index b4fcb34c5..5c0b4a493 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -283,7 +283,6 @@ "group": "Linux Package", "pages": [ "self-hosting/deployment-options/native/linux-package/installation", - "self-hosting/deployment-options/native/linux-package/migration", "self-hosting/deployment-options/native/linux-package/commands-configuration" ] }, diff --git a/docs/self-hosting/deployment-options/native/linux-package/commands-configuration.mdx b/docs/self-hosting/deployment-options/native/linux-package/commands-configuration.mdx index 9746bce13..7aec6867a 100644 --- a/docs/self-hosting/deployment-options/native/linux-package/commands-configuration.mdx +++ b/docs/self-hosting/deployment-options/native/linux-package/commands-configuration.mdx @@ -1,38 +1,38 @@ --- -title: "Commands and Configuration" -description: "Learn all the available commands and configuration of the linux package." +title: "Configurations" +description: "Learn how to configure and manage the Infisical Linux package" --- -## Configuration +## Configuration Overview -All Infisical configuration is managed from a central file called `infisical.rb` located in the `/etc/infisical` directory. +All configuration for the Infisical Linux package is managed through a single file called `infisical.rb`, located in the `/etc/infisical` directory. +This file defines all necessary settings, including encryption keys, database connections, and environment-specific settings. - After updating the `infisical.rb` file, remember to run `infisical-ctl reconfigure` to apply the changes. + After making any changes to the `infisical.rb` file, always run `infisical-ctl reconfigure` to apply them. ### Example Configuration -```ruby +```ruby infisical.rb # Important: Replace these values with secure keys in production infisical_core['ENCRYPTION_KEY'] = '6c1fe4e407b8911c104518103505b218' infisical_core['AUTH_SECRET'] = '5lrMXKKWCVocS/uerPsl7V+TX/aaUaI7iDkgl3tSmLE=' # Database connection strings -infisical_core['DB_CONNECTION_URI'] = 'postgres://infisical:infisical@localhost:5432/infisical' -infisical_core['REDIS_URL'] = 'redis://localhost:6379' +infisical_core['DB_CONNECTION_URI'] = 'postgres://infisical:some-password@some-host:5432/infisical' +infisical_core['REDIS_URL'] = 'redis://some-host:6379' ``` -For a complete list of configuration options, visit our [configuration variables documentation](/self-hosting/configuration/envars). +For a full list of supported configuration variables, refer to the [configuration variables documentation](/self-hosting/configuration/envars). -## Available Commands +## All `infisical-ctl` Commands -The `infisical-ctl` command provides several options to manage your Infisical deployment: +The Infisical Linux package includes the `infisical-ctl` command-line tool, which allows you to manage your deployment. +The available commands are listed below. -| Command | Description | -| --- | --- | -| `infisical-ctl reconfigure` | Restarts the Infisical services and applies any configuration changes | -| `infisical-ctl tail` | Shows the logs of the Infisical application | -| `infisical-ctl status` | Displays the current running status of the Infisical services | -| `infisical-ctl stop` | Stops the Infisical services | -| `infisical-ctl start` | Starts the Infisical services | - -For database migration-related commands, refer to the [Migrations Guide](/self-hosting/native/linux-package/migration). +| Command | Description | +|-----------------------------|-----------------------------------------------------------------------------| +| `infisical-ctl reconfigure` | Applies changes from `infisical.rb` and restarts the Infisical services. | +| `infisical-ctl start` | Starts the Infisical services. | +| `infisical-ctl stop` | Stops all running Infisical services. | +| `infisical-ctl status` | Displays the current status of the Infisical services. | +| `infisical-ctl tail` | Streams real-time logs from the Infisical application. | \ No newline at end of file diff --git a/docs/self-hosting/deployment-options/native/linux-package/installation.mdx b/docs/self-hosting/deployment-options/native/linux-package/installation.mdx index 91a171adf..e9aa5b19d 100644 --- a/docs/self-hosting/deployment-options/native/linux-package/installation.mdx +++ b/docs/self-hosting/deployment-options/native/linux-package/installation.mdx @@ -1,102 +1,124 @@ --- title: "Installation" -description: "Learn how to deploy Infisical using linux package." +description: "Learn how to deploy Infisical using the Linux package" --- -Infisical can be deployed on Linux virtual machines without containers using our Linux packages. Currently, we support Linux systems running on AMD64 architecture (ARM coming soon). - -This standalone deployment uses a "Bring Your Own Database" (BYOD) approach, meaning you'll need to provide your own PostgreSQL and Redis databases for Infisical services. These databases are not included in the package. +Infisical can be deployed on Linux virtual machines without the need for containers using our standalone Linux packages. +These packages are available in both .deb (for Debian-based systems) and .rpm (for RHEL-based systems) formats. +The installation includes the Infisical service, along with a CLI tool (infisical-ctl) to help you manage configurations, startup, and application logging. +This approach is ideal for environments where containerization isn't desired, while still providing a lightweight deployment option. ## Prerequisites -Before beginning the installation, ensure you have: +This installation method only provides the Infisical application. You are responsible for configuring both PostgreSQL and Redis, either by using managed services (e.g., AWS RDS, Azure Database, GCP Cloud SQL/Memorystore) or by deploying them manually in your on-prem environment. +Please ensure you have the following before beginning installation of Infisical: -- A server running a linux-based operating system (Ubuntu, Debian) or RHEL-based system -- A PostgreSQL database instance -- A Redis database instance +- A Linux server running a Debian/Ubuntu or RHEL-based distribution +- A running PostgreSQL database instance +- A running Redis database instance ## Installation Steps - -Choose your operating system below to install Infisical: - + + Select your Linux distribution to get started. Only AMD64-based systems are supported at this time, ARM support is coming soon. + + + - First, add the Infisical repository: - ```bash - curl -1sLf \ - 'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.deb.sh' \ - | sudo -E bash - ``` + Add the Infisical repository: + ```bash + curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.deb.sh' | sudo -E bash + ``` - Then install Infisical: - ```bash - sudo apt-get update && sudo apt-get install -y infisical-core - ``` - - > **Note**: For production environments, we strongly recommend installing a specific version of the package to maintain consistency across reinstalls. View available versions at [Infisical Package Versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/). + Install Infisical: + ```bash + sudo apt-get update && sudo apt-get install -y infisical-core + ``` + > **Note**: For production use, we recommend locking to a specific version to ensure consistency. [View available versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/). - First, add the Infisical repository: - ```bash - curl -1sLf \ - 'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.rpm.sh' \ - | sudo -E bash - ``` + Add the Infisical repository: + ```bash + curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-core/setup.rpm.sh' | sudo -E bash + ``` - Then install Infisical: - ```bash - sudo yum install infisical-core - ``` - - > **Note**: For production environments, we strongly recommend installing a specific version of the package to maintain consistency across reinstalls. View available versions at [Infisical Package Versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/). + Install Infisical: + ```bash + sudo yum install infisical-core + ``` + > **Note**: For production use, we recommend locking to a specific version to ensure consistency. [View available versions](https://cloudsmith.io/~infisical/repos/infisical-core/packages/). - -To verify the installation, run: + -```bash -infisical-ctl help -``` + Verify the installation: + ```bash + infisical-ctl help + ``` + - - -Create an `infisical.rb` file in the `/etc/infisical` directory. This file will contain your database connections and other configuration settings. + + Create an `infisical.rb` file at `/etc/infisical`. This file contains your database connection strings and other runtime settings. - -```ruby -# Important: Replace these values with secure keys in production -infisical_core['ENCRYPTION_KEY'] = '6c1fe4e407b8911c104518103505b218' -infisical_core['AUTH_SECRET'] = '5lrMXKKWCVocS/uerPsl7V+TX/aaUaI7iDkgl3tSmLE=' + ```ruby + # Important: Replace with secure values in production + infisical_core['ENCRYPTION_KEY'] = '6c1fe4e407b8911c104518103505b218' + infisical_core['AUTH_SECRET'] = '5lrMXKKWCVocS/uerPsl7V+TX/aaUaI7iDkgl3tSmLE=' -# Database connection strings -infisical_core['DB_CONNECTION_URI'] = 'postgres://infisical:infisical@localhost:5432/infisical' -infisical_core['REDIS_URL'] = 'redis://localhost:6379' -``` - + # Example database connection strings + infisical_core['DB_CONNECTION_URI'] = 'postgres://:@:/' + infisical_core['REDIS_URL'] = 'redis://:' + ``` -For a complete list of configuration options, visit our [configuration variables documentation](/self-hosting/configuration/envars). + See the full list of options in our [configuration documentation](/self-hosting/configuration/envars). + - - -1. Run the following command to start the Infisical server: - ```bash - infisical-ctl reconfigure - ``` - By default, the server will run on port `8080`. You can modify this in the `infisical.rb` configuration file. + + 1. Start the Infisical service: + ```bash + infisical-ctl reconfigure + ``` + The server runs on port `8080` by default (customizable in `infisical.rb`). + + 2. Check the service status: + + Check the service status: + ```bash + infisical-ctl status + ``` + + View the service logs in real-time: + ```bash + infisical-ctl tail + ``` + -2. Monitor your deployment: - - Check the application status: - ```bash - infisical-ctl status - ``` - - View real-time logs: - ```bash - infisical-ctl tail - ``` - + +## Platform Support + +### Microsoft Windows +Infisical is built for Linux-based systems. It is not supported on Microsoft Windows, and we do not plan to support it in the near future. For Windows users, consider running Infisical in a virtual machine or WSL2 environment. + +### Unsupported Linux Distributions and Unix-like Systems +Infisical is not tested or officially supported on the following: + +- Arch Linux +- Fedora +- FreeBSD +- Gentoo +- macOS + +We recommend sticking to officially supported distributions for the best experience. + +## Linux vs Containerized Deployments + +Infisical is a stateless application, which means it can be easily scaled and redeployed without maintaining internal state between instances. + +If your use case requires rolling updates, self-healing, or auto-scaling, we recommend deploying Infisical in a containerized environment such as Kubernetes/OpenShift, or using managed container orchestration services like AWS ECS or Google Cloud Run. +These platforms offer built-in capabilities for high availability and help simplify operational overhead for your deployment. \ No newline at end of file diff --git a/docs/self-hosting/deployment-options/native/linux-package/migration.mdx b/docs/self-hosting/deployment-options/native/linux-package/migration.mdx deleted file mode 100644 index 50dca04af..000000000 --- a/docs/self-hosting/deployment-options/native/linux-package/migration.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Migration" -description: "Learn how to run migration using Infisical linux package." ---- - -By default, migrations automatically run each time you execute `infisical-ctl reconfigure`. This behavior may not be desirable when deploying with horizontal scaling. - -## Disable Auto Migration - -To disable automatic migrations, add the following configuration to your `infisical.rb` file: - -```ruby -infisical_core['auto_migration'] = false -``` - -## Migration Commands - -`infisical-ctl` provides several commands to manage database migrations. You can run these commands in two ways: - -- Provide the PostgreSQL database connection as an environment variable, or -- Let the system load the connection details from the Infisical application after reconfiguration - -| Command | Description | -| ---------------------------------- | --------------------------------------------------------------------------- | -| `infisical-ctl migration up` | Runs the next migration that hasn't been applied yet | -| `infisical-ctl migration down` | Reverts the most recent migration, undoing its changes | -| `infisical-ctl migration list` | Lists all available migration files without applying them | -| `infisical-ctl migration status` | Displays the status of each migration, showing which have been applied | -| `infisical-ctl migration latest` | Applies all pending migrations to bring the database up to date | -| `infisical-ctl migration rollback` | Reverts all applied migrations, returning the database to its initial state | diff --git a/docs/self-hosting/overview.mdx b/docs/self-hosting/overview.mdx index f1bbfe236..51122758d 100644 --- a/docs/self-hosting/overview.mdx +++ b/docs/self-hosting/overview.mdx @@ -34,9 +34,8 @@ Choose from a number of deployment options listed below to get started. Install Infisical on your system without containers using our linux package.