diff --git a/docs/docs.json b/docs/docs.json index 81dc2f9a46f..1c28e2e40cb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -21,6 +21,8 @@ "pages": [ "documentation/getting-started/overview", "documentation/getting-started/introduction", + "documentation/getting-started/quickstart", + "documentation/getting-started/self-hosted-quickstart", { "group": "Concepts", "pages": [ @@ -347,6 +349,7 @@ "self-hosting/guides/mongo-to-postgres", "self-hosting/guides/custom-certificates", "self-hosting/guides/automated-bootstrapping", + "self-hosting/guides/end-to-end-automation", "self-hosting/guides/production-hardening", "self-hosting/guides/monitoring-telemetry" ] diff --git a/docs/documentation/getting-started/quickstart.mdx b/docs/documentation/getting-started/quickstart.mdx new file mode 100644 index 00000000000..d8f626c0c6c --- /dev/null +++ b/docs/documentation/getting-started/quickstart.mdx @@ -0,0 +1,172 @@ +--- +title: "Get Started in 5 Minutes" +sidebarTitle: "5-Minute Quickstart" +description: "Go from zero to retrieving your first secret with Infisical Cloud and the CLI." +--- + +This guide walks you through the complete flow: create an account, store a secret, and retrieve it in your app. By the end, you'll have Infisical injecting environment variables into a running process. + +If you'd rather run Infisical on your own infrastructure, start with the [Self-Hosted Quickstart](/documentation/getting-started/self-hosted-quickstart) instead. + +## Prerequisites + +- A terminal (macOS, Linux, or WSL on Windows) +- An application that reads environment variables (any language/framework) + +## Step 1: Create your Infisical Cloud account + +Go to [app.infisical.com](https://app.infisical.com) and sign up. You can use email, Google, GitHub, GitLab, or SAML SSO. + +After signing up, Infisical creates your first **organization** automatically. An organization is the top-level container that holds your projects, team members, and billing. + +## Step 2: Create a project and add a secret + +1. From the organization dashboard, click **Add New Project** and select **Secret Manager**. +2. Give it a name (e.g. `my-app`) and click **Create Project**. +3. You'll land in the **Secrets** dashboard. You're in the **Development** environment by default — Infisical ships with **Development**, **Staging**, and **Production** environments out of the box. +4. Click **Add Secret**. Enter a key and value: + - **Key:** `GREETING` + - **Value:** `Hello from Infisical!` +5. The secret saves automatically. + +You now have one secret stored in your project's Development environment. + + + Migrating from an existing `.env` file? You can bulk-import in two ways: + - **From the dashboard:** click the **Actions** dropdown and select **Import from .env** to upload your file. + - **From the CLI** (after Step 4): `infisical secrets set --file=".env" --env=dev`. Supports `.env` and YAML formats; `#` and `//` comments are ignored. + + +## Step 3: Install the Infisical CLI + + + + ```bash + brew install infisical/get-cli/infisical + ``` + + + ```bash + curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | sudo -E bash + sudo apt-get update && sudo apt-get install -y infisical + ``` + + + ```bash + curl -1sLf 'https://artifacts-cli.infisical.com/setup.rpm.sh' | sudo -E bash + sudo yum install infisical + ``` + + + ```bash + scoop bucket add org https://github.com/Infisical/scoop-infisical.git + scoop install infisical + ``` + + + ```bash + apk add --no-cache bash sudo wget + wget -qO- 'https://artifacts-cli.infisical.com/setup.apk.sh' | sudo sh + apk update && sudo apk add infisical + ``` + + + ```bash + yay -S infisical-bin + ``` + + + +Verify the installation: + +```bash +infisical --version +``` + +## Step 4: Log in and link your project + +```bash +# Authenticate with Infisical Cloud (opens your browser) +infisical login + +# Navigate to your project directory +cd /path/to/your/project + +# Link this directory to your Infisical project (select it from the list) +infisical init +``` + +The `init` command creates a `.infisical.json` file in your project root. This file only contains a project ID reference (stored as `workspaceId`) — no secrets — so it's safe to commit to version control. + + + Want different environments per git branch? Add a `gitBranchToEnvironmentMapping` block to `.infisical.json` and the CLI will pick the environment to fetch from automatically based on your current branch: + + ```json .infisical.json + { + "workspaceId": "63ee5410a45f7a1ed39ba118", + "gitBranchToEnvironmentMapping": { + "main": "prod", + "staging": "staging", + "develop": "dev" + } + } + ``` + + +## Step 5: Retrieve your secret + +There are three ways to use your secrets. Pick whichever fits your workflow. + +### Option A: Inject into a running process + +The most common approach. `infisical run` fetches your secrets and passes them as environment variables to whatever command follows `--`: + +```bash +infisical run --env=dev -- printenv GREETING +# Output: Hello from Infisical! +``` + +Replace `printenv GREETING` with your real start command: + +```bash +infisical run --env=dev -- npm run dev +infisical run --env=dev -- python app.py +infisical run --env=dev -- go run main.go +``` + +Your application reads `process.env.GREETING` (or the equivalent in your language) exactly as it would with a `.env` file — no code changes needed. + +### Option B: Export to a file + +Generate a `.env` file from your Infisical secrets: + +```bash +infisical export --env=dev --format=dotenv > .env +``` + +Other supported formats: `yaml`, `json`, `csv`, `dotenv-export`. + +### Option C: List secrets in the terminal + +Inspect what's stored without running an app: + +```bash +infisical secrets --env=dev +``` + +## What's next + +You've stored a secret and retrieved it. Here's where to go from here: + +- **Add your team:** Invite members from the organization settings page. They install the CLI, run `infisical login` and `infisical init`, and instantly have access to the same secrets — no `.env` files changing hands. +- **Use environments:** Your project already has Development, Staging, and Production environments. Switch between them with the `--env` flag (`dev`, `staging`, `prod`). +- **Set up CI/CD and production:** For non-interactive environments, create a [Machine Identity](/documentation/platform/identities/machine-identities) instead of using personal login. Machine identities use client credentials that can be scoped to specific projects and environments. Once you have an identity token, set `INFISICAL_TOKEN` in the environment and every CLI command will use it — no `infisical login` required: + + ```bash + export INFISICAL_TOKEN=$(infisical login --method=universal-auth \ + --client-id="" --client-secret="" --plain --silent) + infisical run --env=prod -- your-start-command + ``` +- **Use an SDK instead of the CLI:** Infisical has native SDKs for [Node.js, Python, Go, Java, .NET, Ruby, PHP, Rust, and C++](/sdks/overview). SDKs fetch secrets at runtime from your application code. +- **Explore integrations:** Sync secrets to [AWS Parameter Store, Vercel, GitHub Actions, Kubernetes, and more](/integrations/secret-syncs). +- **Self-host:** To run Infisical on your own infrastructure, follow the [Self-Hosted Quickstart](/documentation/getting-started/self-hosted-quickstart) for a local setup, or the [self-hosting overview](/self-hosting/overview) for deployment options. diff --git a/docs/documentation/getting-started/self-hosted-quickstart.mdx b/docs/documentation/getting-started/self-hosted-quickstart.mdx new file mode 100644 index 00000000000..b421d739b92 --- /dev/null +++ b/docs/documentation/getting-started/self-hosted-quickstart.mdx @@ -0,0 +1,117 @@ +--- +title: "Quickstart with Self-Hosted Infisical" +sidebarTitle: "Self-Hosted Quickstart" +description: "Run Infisical locally with Docker Compose, bootstrap an admin account, and retrieve your first secret from the CLI." +--- + +This guide gets a self-hosted Infisical instance running on your machine and walks you through retrieving your first secret from it. By the end, you'll have Infisical injecting environment variables into a process — with no reliance on Infisical Cloud. + +If you're trying Infisical for the first time and don't need to self-host, use the [Cloud quickstart](/documentation/getting-started/quickstart) instead. + +## Prerequisites + +- [Docker Engine](https://docs.docker.com/engine/install/) (20.10+) and [Docker Compose](https://docs.docker.com/compose/install/) (v2+) +- A terminal (macOS, Linux, or WSL on Windows) + +## Step 1: Start Infisical locally + +Download the production Docker Compose file and the default environment variables, then start the stack: + +```bash +curl -o docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml +curl -o .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example + +docker compose -f docker-compose.prod.yml up -d +``` + +This starts three containers: the Infisical backend (exposed on port 80), PostgreSQL, and Redis. + + + If you have run this stack before, old database volumes may still exist with different credentials than your current `.env`. Run `docker compose -f docker-compose.prod.yml down -v` first to wipe them — otherwise the database will reject connections with an authentication error. + + + + The downloaded `.env` file contains credentials that control the security of your deployment. Do not commit it, and tighten its permissions: + + ```bash + chmod 600 .env + ``` + + +Confirm the backend is responding: + +```bash +curl -s http://localhost:80/api/status | head -c 100 +``` + +For the full set of configuration options and production-grade deployments, see the [Docker Compose guide](/self-hosting/deployment-options/docker-compose). + +## Step 2: Bootstrap the instance + +Fresh Infisical instances have no users, organizations, or identities. Instead of creating the first admin through the UI, use the `infisical bootstrap` command — it creates the admin user, an organization, and an **instance admin machine identity** in a single call, and returns a JWT token you can use for further automation: + +```bash +infisical bootstrap \ + --domain="http://localhost:80" \ + --email="admin@example.com" \ + --password="your-secure-password" \ + --organization="my-org" \ + --ignore-if-bootstrapped +``` + +The response is a JSON object containing the new user, organization, and identity — including an `identity.credentials.token` field. For a full breakdown of the response and alternative bootstrap methods (API, Helm), see [Programmatic Provisioning](/self-hosting/guides/automated-bootstrapping). + + + Don't have the CLI yet? Install it with `brew install infisical/get-cli/infisical` (macOS) or see Step 3 of the [Cloud quickstart](/documentation/getting-started/quickstart#step-3-install-the-infisical-cli) for other platforms. + + +## Step 3: Create a project and add a secret + +Open [http://localhost:80](http://localhost:80) in your browser and log in with the admin credentials you bootstrapped. + +1. From the organization dashboard, click **Add New Project** and select **Secret Manager**. +2. Give it a name (e.g. `my-app`) and click **Create Project**. +3. You'll land in the **Secrets** dashboard in the **Development** environment. +4. Click **Add Secret**. Enter: + - **Key:** `GREETING` + - **Value:** `Hello from self-hosted Infisical!` +5. The secret saves automatically. + + + Want to skip the UI entirely? The [End-to-End Automation guide](/self-hosting/guides/end-to-end-automation) shows how to script project creation and secret import using the bootstrap token. + + +## Step 4: Point the CLI at your self-hosted instance + +By default, the CLI talks to Infisical Cloud. Set the domain to your local instance, then log in as the admin user: + +```bash +infisical login --domain="http://localhost:80" +``` + +Link your project directory: + +```bash +cd /path/to/your/project +infisical init +``` + +`init` writes a `.infisical.json` file containing the project ID (stored as `workspaceId`) — no secrets, safe to commit. + +## Step 5: Retrieve your secret + +Run any command with `infisical run` and your secrets are injected as environment variables: + +```bash +infisical run --env=dev -- printenv GREETING +# Output: Hello from self-hosted Infisical! +``` + +Replace `printenv GREETING` with your real start command — `npm run dev`, `python app.py`, `go run main.go`, and so on. Your app reads `process.env.GREETING` (or the language equivalent) exactly as it would with a `.env` file. + +## What's next + +- **Automate the whole flow:** See the [End-to-End Automation guide](/self-hosting/guides/end-to-end-automation) for a scripted path from empty instance to running app. +- **Production-grade deployment:** The steps above are a local proof of concept. For high-availability setups, review the [Kubernetes Helm guide](/self-hosting/deployment-options/kubernetes-helm) and the [reference architectures](/self-hosting/reference-architectures/on-prem-k8s-ha). +- **Secure your instance:** See [Production Hardening](/self-hosting/guides/production-hardening) before exposing the instance beyond your local machine. +- **Use an SDK instead of the CLI:** Infisical has native SDKs for [Node.js, Python, Go, Java, .NET, Ruby, PHP, Rust, and C++](/sdks/overview). diff --git a/docs/self-hosting/guides/end-to-end-automation.mdx b/docs/self-hosting/guides/end-to-end-automation.mdx new file mode 100644 index 00000000000..51bbb43ea37 --- /dev/null +++ b/docs/self-hosting/guides/end-to-end-automation.mdx @@ -0,0 +1,175 @@ +--- +title: "End-to-End Automation" +description: "Script a self-hosted Infisical instance from empty to running application — bootstrap, project creation, secret import, and runtime injection, without any UI interaction." +--- + +This guide shows how to take a freshly started self-hosted Infisical instance to the point where an application is running with its secrets injected by the CLI — without a single UI click. It chains together the [bootstrap flow](/self-hosting/guides/automated-bootstrapping), the [projects API](/api-reference/endpoints/projects/create-project), and the [CLI](/cli/overview) into a single reproducible script. + +Use this when you're provisioning a new environment from infrastructure-as-code, seeding a local development setup for a team, or writing a test harness that needs Infisical stood up on demand. + + + **Minimal path vs. full automation.** This guide presents the complete scripted flow. If you only need the app running locally without `.env`, steps 1–5 can each be done manually in a few commands — you don't need a shell script. The script format is most useful when this setup needs to be repeatable or automated. Avoid writing a reusable setup script unless your workflow will actually re-run it. + + +## Prerequisites + +- A self-hosted Infisical instance already running (see the [Self-Hosted Quickstart](/documentation/getting-started/self-hosted-quickstart) or the [Docker Compose deployment guide](/self-hosting/deployment-options/docker-compose)) +- The [Infisical CLI](/cli/overview) installed locally +- An application that reads its configuration from environment variables +- `curl` and `jq` available for the API calls + +## The flow at a glance + + + + Create the admin user, organization, and instance admin machine identity in a single command. Capture the returned token for reuse. + + + Use the bootstrap token to POST to the projects endpoint. Capture the project ID. + + + Feed an existing `.env` file straight into the project with `infisical secrets set --file`. + + + Link your application directory to the project without the interactive `infisical init` prompt. + + + Start your process under `infisical run` with the machine identity token in the environment. + + + +## The script + +The snippet below is the complete end-to-end flow. Each block is explained in the section that follows. + +```bash +#!/usr/bin/env bash +set -euo pipefail + +DOMAIN="http://localhost:80" +ADMIN_EMAIL="admin@example.com" +ADMIN_PASSWORD="your-secure-password" +ORG_NAME="my-org" +PROJECT_NAME="my-app" + +# 1. Bootstrap +BOOTSTRAP=$(infisical bootstrap \ + --domain="$DOMAIN" \ + --email="$ADMIN_EMAIL" \ + --password="$ADMIN_PASSWORD" \ + --organization="$ORG_NAME" \ + --ignore-if-bootstrapped) + +export INFISICAL_TOKEN=$(echo "$BOOTSTRAP" | jq -r '.identity.credentials.token') + +# 2. Create a project +PROJECT_ID=$(curl -sX POST "$DOMAIN/api/v1/projects" \ + -H "Authorization: Bearer $INFISICAL_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"projectName\":\"$PROJECT_NAME\",\"type\":\"secret-manager\"}" \ + | jq -r '.project.id') + +# 3. Push every secret from the local .env file into the dev environment +infisical secrets set \ + --projectId="$PROJECT_ID" \ + --env=dev \ + --file=".env" + +# 4. Link the repo to the project without running `infisical init` +cat > .infisical.json < + The bootstrap token has instance-level admin privileges. Treat it as a root credential: store it securely, scope its use to automation, and rotate it periodically via the server admin panel. + + +### 2. Create a project + +With the bootstrap token in hand, any API call the token is authorized for is available without further auth steps. The [`POST /api/v1/projects`](/api-reference/endpoints/projects/create-project) endpoint creates a new Secret Manager project; the response includes a `project.id` field used by the CLI as the `workspaceId`. + +### 3. Push secrets + +`infisical secrets set --file` performs a single bulk import from a file on disk. It accepts both `.env` (`KEY=value`) and YAML (`key: value`) formats. Comments beginning with `#` or `//` and empty lines are ignored. See the [secrets command reference](/cli/commands/secrets) for the full flag list. + + + Running this multiple times is safe: `infisical secrets set` creates missing keys and updates existing ones in place. This makes it easy to re-run the script as your `.env` evolves. + + +### 4. Write `.infisical.json` + +The `infisical init` command is designed for interactive use — it prompts for a project selection. In a script, it's faster to write the file directly. The minimum valid config is just the project ID: + +```json .infisical.json +{ + "workspaceId": "", + "defaultEnvironment": "dev" +} +``` + +The file contains no secrets and is safe to commit. See the [project config reference](/cli/project-config) for optional fields, including `gitBranchToEnvironmentMapping` for automatically switching environments based on the current git branch. + +### 5. Run the application + +`infisical run` reads secrets from the project and injects them as environment variables into the child process. Because `INFISICAL_TOKEN` is already exported, the CLI authenticates without an interactive login, and because `.infisical.json` sets the default environment, the `--env` flag can be omitted. + +Inside your application, secrets appear exactly as if they came from a `.env` file — `process.env.MY_KEY`, `os.environ["MY_KEY"]`, and so on. No SDK is required and no code change is needed when moving from dotenv to Infisical. + + + When `INFISICAL_TOKEN` is a machine identity token (as opposed to a session from `infisical login`), the `--projectId` flag is required — the CLI cannot infer the project from the token alone. If `.infisical.json` is present, pass the project ID explicitly anyway to be safe: + + ```bash + infisical run --projectId="$PROJECT_ID" -- your-start-command + ``` + + +## Using a scoped machine identity instead of the bootstrap token + +The bootstrap token is convenient but over-privileged for running a single application. Once the instance is bootstrapped, create a project-scoped [Machine Identity](/documentation/platform/identities/machine-identities) with Universal Auth and swap it in: + +```bash +export INFISICAL_TOKEN=$(infisical login --method=universal-auth \ + --client-id="" \ + --client-secret="" \ + --domain="$DOMAIN" \ + --plain --silent) + +infisical run -- your-start-command +``` + +This is the pattern you want for CI/CD pipelines and long-lived production workloads. The bootstrap token stays locked away and is used only for provisioning. + +## Important notes + +- **Docker networking.** If your application also runs in Docker and needs to reach a containerized Infisical instance, use the container service name (e.g. `http://backend:8080`) rather than `http://localhost`. `localhost` inside a container refers to the container itself. +- **HTTPS and cookies.** If you skip TLS on a local instance, set `HTTPS_ENABLED=false` in the Infisical backend's environment. Without this, the CLI may log out on every request because of secure-cookie requirements. See the [self-hosting FAQ](/self-hosting/faq) for details. +- **Readiness timing.** On slower machines or in CI, the Infisical backend can take a few seconds to become healthy after `docker compose up`. If the bootstrap call races the backend, poll `/api/status` before bootstrapping: + + ```bash + until curl -sf "$DOMAIN/api/status" >/dev/null; do sleep 1; done + ``` +- **Idempotency beyond bootstrap.** `--ignore-if-bootstrapped` makes step 1 safe to re-run, but step 2 (project creation) is not idempotent — a repeated call with the same project name will fail. Either check for the project first via `GET /api/v1/projects`, or catch the error and fetch the existing project ID. + +## What's next + +- [Programmatic Provisioning](/self-hosting/guides/automated-bootstrapping) — deeper dive into the bootstrap flow, including API and Helm variants. +- [Machine Identities](/documentation/platform/identities/machine-identities) — scoped credentials for production automation. +- [Production Hardening](/self-hosting/guides/production-hardening) — before using this pattern in a shared environment. +- [CLI command reference](/cli/overview) — full flag documentation for `bootstrap`, `secrets`, `run`, and `login`.