diff --git a/src/README.md b/src/README.md index 9629b3f..8b021c9 100644 --- a/src/README.md +++ b/src/README.md @@ -1,41 +1,43 @@ # Welcome to Semaphore UI -## What is Semaphore UI? - -Semaphore UI is a modern UI and powerful API for Ansible, Terraform, OpenTofu, PowerShell and other DevOps tools. +Semaphore UI is a modern interface and API for running Ansible, Terraform/OpenTofu, PowerShell, Python, and shell automation with minimal overhead. This documentation helps you evaluate, deploy, and operate Semaphore confidently. -Semaphore is written in pure Go and available for Windows, macOS and Linux (x64, ARM, ARM64). Semaphore is an open-source project with concise and high-quality code. +## Why Semaphore -Semaphore supports the following databases: +Semaphore is written in Go and ships as a single binary for Windows, macOS, and Linux (x64, ARM, ARM64). It pairs a lightweight architecture with enterprise features: -* MySQL -* PostgreSQL -* [BoltDB](https://github.com/etcd-io/bbolt) – embedded key/value database +* Works with MySQL, PostgreSQL, or embedded BoltDB. +* Encrypts secrets at rest and integrates with LDAP and OpenID Connect. +* Offers a responsive web UI, REST API, and CLI for the same workflows. +* Scales horizontally with remote runners and project-scoped permissions. With Semaphore you can: -* [Build, deploy and rollback](./administration-guide/cicd.md) -* Group playbooks to projects -* Manage environments, inventories, repositories and access keys -* Run playbooks from the browser. Responsive UI allows the use of Semaphore on mobile devices -* Run playbooks by schedule -* View detailed logs of any playbook runs, at any time -* Delegate other users the running of playbooks -* Get notifications about playbook runs +* [Build, deploy, and roll back automation pipelines](./administration-guide/cicd.md). +* Organize playbooks and scripts into projects with fine-grained access control. +* Manage inventories, repositories, secrets, and environment variables centrally. +* Run tasks manually, on schedules, or through the API/CLI, and monitor detailed logs. +* Notify teams via email, chat, and webhooks when automation completes. + +## Where to start + +* **New to Semaphore?** Begin with [Getting Started](./getting-started/README.md) for a 10-minute quick start, core concepts, and a UI tour. +* **Running production?** Jump to the [Admin Guide](./administration-guide/README.md) for installation, configuration, security, and integration topics. +* **Operating day-to-day?** Head over to the [User Guide](./user-guide/README.md) to learn how to create projects, templates, and schedules. -## Links +## Helpful links * Source code: [https://github.com/semaphoreui/semaphore](https://github.com/semaphoreui/semaphore) * Issue tracking: [https://github.com/semaphoreui/semaphore/issues](https://github.com/semaphoreui/semaphore/issues) -* Docker: [https://hub.docker.com/r/semaphoreui/semaphore](https://hub.docker.com/r/semaphoreui/semaphore) -* Snap: [https://snapcraft.io/semaphore](https://snapcraft.io/semaphore) +* Docker images: [https://hub.docker.com/r/semaphoreui/semaphore](https://hub.docker.com/r/semaphoreui/semaphore) +* Snap package: [https://snapcraft.io/semaphore](https://snapcraft.io/semaphore) * Contact: [denis@semaphoreui.com](mailto:denis@semaphoreui.com) * Docker container configurator: - [![](https://img.shields.io/badge/docker_configurator-0050ab?style=for-the-badge&logo=docker)](https://semaphoreui.com/install/docker/) + [![](https://img.shields.io/badge/docker_configurator-0050ab?style=for-the-badge&logo=docker)](https://semaphoreui.com/install/docker/) -* Our responsive community: +* Community chat: - [![discord](https://img.shields.io/badge/discord_community-510b80?style=for-the-badge&logo=discord)](https://discord.gg/5R6k7hNGcH) \ No newline at end of file + [![discord](https://img.shields.io/badge/discord_community-510b80?style=for-the-badge&logo=discord)](https://discord.gg/5R6k7hNGcH) \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e6c66c7..80e5488 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,93 +2,93 @@ * [Welcome to Semaphore UI](./README.md) +* [Getting Started](./getting-started/README.md) + * [Quick Start](./getting-started/quickstart.md) + * [Core Concepts](./getting-started/concepts.md) + * [UI Tour](./getting-started/ui-tour.md) + * [Next Steps](./getting-started/next-steps.md) + * [Admin Guide](./administration-guide/README.md) - - * [Installation](./administration-guide/installation.md) + * [Plan & Install](./administration-guide/installation.md) * [Package manager](./administration-guide/installation/package-manager.md) * [Docker](./administration-guide/installation/docker.md) * [Cloud](./administration-guide/installation/cloud.md) * [Binary file](./administration-guide/installation/binary-file.md) * [Kubernetes (Helm chart)](./administration-guide/installation/k8s.md) + * [Manual installation](./administration-guide/installation_manually.md) * [Snap (deprecated)](./administration-guide/installation/snap.md) - * [Manual Installation](./administration-guide/installation\_manually.md) - * [Configuration](./administration-guide/configuration.md) + * [Configure & Harden](./administration-guide/configuration.md) * [Configuration file](./administration-guide/configuration/config-file.md) * [Environment variables](./administration-guide/configuration/env-vars.md) * [Interactive setup](./administration-guide/configuration/cli.md) - * [Snap configuration](./administration-guide/configuration/snap.md) - * [Upgrading](./administration-guide/upgrading.md) - * [Security](./administration-guide/security.md) - * [Database security](./administration-guide/security/database.md) - * [Network security](./administration-guide/security/network.md) - * [NGINX config](./administration-guide/security/nginx.md) - * [Apache config](./administration-guide/security/apache.md) - * [Kerberos](./administration-guide/security/kerberos.md) - * [CLI](./administration-guide/cli.md) - * [Users](./administration-guide/cli/users.md) - * [Vaults](./administration-guide/cli/vaults.md) - * [Runners](./administration-guide/cli/runners.md) - * [Database migrations](./administration-guide/cli/migrations.md) - * [LDAP](./administration-guide/ldap.md) - * [OpenID](./administration-guide/openid.md) - * [GitHub config](./administration-guide/openid/github.md) - * [Google config](./administration-guide/openid/google.md) - * [GitLab config](./administration-guide/openid/gitlab.md) - * [Gitea config](./administration-guide/openid/gitea.md) - * [Authelia config](./administration-guide/openid/authelia.md) - * [Authentik config](./administration-guide/openid/authentik.md) - * [Keycloak config](./administration-guide/openid/keycloak.md) - * [Okta config](./administration-guide/openid/okta.md) - * [Azure config](./administration-guide/openid/azure.md) - * [Zitadel config](./administration-guide/openid/zitadel.md) - * [API](./administration-guide/api.md) - * [Pipelines](./administration-guide/cicd.md) - * [Runners](./administration-guide/runners.md) - * [Logs](./administration-guide/logs.md) - * [Notifications](./administration-guide/notifications.md) - * [Email](./administration-guide/notifications/email.md) - * [Telegram](./administration-guide/notifications/telegram.md) - * [Slack](./administration-guide/notifications/slack.md) - * [Teams](./administration-guide/notifications/teams.md) - * [Rocket.Chat](./administration-guide/notifications/rocket.md) - * [DingTalk](./administration-guide/notifications/ding.md) - * [Gotify](./administration-guide/notifications/gotify.md) - - * [Troubleshooting](./administration-guide/troubleshooting.md) + * [Security overview](./administration-guide/security.md) + * [Database security](./administration-guide/security/database.md) + * [Network security](./administration-guide/security/network.md) + * [NGINX config](./administration-guide/security/nginx.md) + * [Apache config](./administration-guide/security/apache.md) + * [Kerberos](./administration-guide/security/kerberos.md) + * [Authenticate & Authorize](./administration-guide/openid.md) + * [LDAP](./administration-guide/ldap.md) + * [OpenID: provider setup](./administration-guide/openid.md) + * [GitHub config](./administration-guide/openid/github.md) + * [Google config](./administration-guide/openid/google.md) + * [GitLab config](./administration-guide/openid/gitlab.md) + * [Gitea config](./administration-guide/openid/gitea.md) + * [Authelia config](./administration-guide/openid/authelia.md) + * [Authentik config](./administration-guide/openid/authentik.md) + * [Keycloak config](./administration-guide/openid/keycloak.md) + * [Okta config](./administration-guide/openid/okta.md) + * [Azure config](./administration-guide/openid/azure.md) + * [Zitadel config](./administration-guide/openid/zitadel.md) + * [Integrate & Automate](./administration-guide/cicd.md) + * [API](./administration-guide/api.md) + * [CLI](./administration-guide/cli.md) + * [Users](./administration-guide/cli/users.md) + * [Vaults](./administration-guide/cli/vaults.md) + * [Runners](./administration-guide/cli/runners.md) + * [Database migrations](./administration-guide/cli/migrations.md) + * [Runners](./administration-guide/runners.md) + * [Logs](./administration-guide/logs.md) + * [Notifications](./administration-guide/notifications.md) + * [Email](./administration-guide/notifications/email.md) + * [Telegram](./administration-guide/notifications/telegram.md) + * [Slack](./administration-guide/notifications/slack.md) + * [Teams](./administration-guide/notifications/teams.md) + * [Rocket.Chat](./administration-guide/notifications/rocket.md) + * [DingTalk](./administration-guide/notifications/ding.md) + * [Gotify](./administration-guide/notifications/gotify.md) + * [Maintain & Recover](./administration-guide/upgrading.md) + * [Troubleshooting](./administration-guide/troubleshooting.md) * [User Guide](./user-guide/README.md) - * [Projects](./user-guide/projects.md) + * [Organize work](./user-guide/projects.md) * [History](./user-guide/projects/history.md) * [Activity](./user-guide/projects/activity.md) * [Settings](./user-guide/projects/settings.md) + * [Team](./user-guide/team.md) * [Runners (Pro)](./user-guide/projects/runners.md) - * [Task Templates](./user-guide/task-templates/README.md) + * [Connect resources](./user-guide/repositories.md) + * [Repositories](./user-guide/repositories.md) + * [Bitbucket Access Token](./user-guide/repositories/bitbucket_access_token.md) + * [Inventory](./user-guide/inventory.md) + * [Kerberos](./user-guide/inventory/kerberos.md) + * [NetBox dynamic inventory](./user-guide/netbox-dynamic-inventory.md) + * [Variable Groups](./user-guide/environment.md) + * [Key Store](./user-guide/key-store.md) + * [GitLab](./user-guide/key-store/gitlab.md) + * [Build automation](./user-guide/task-templates/README.md) * [Ansible](./user-guide/task-templates/apps/ansible.md) * [Terraform/OpenTofu](./user-guide/task-templates/apps/terraform.md) - * [Workspaces](./user-guide/task-templates/apps/terraform/workspaces.md) - * [HTTP Backend (Pro)](./user-guide/task-templates/apps/terraform/states.md) + * [Workspaces](./user-guide/task-templates/apps/terraform/workspaces.md) + * [HTTP Backend (Pro)](./user-guide/task-templates/apps/terraform/states.md) * [Shell/Bash scripts](./user-guide/task-templates/apps/bash.md) * [PowerShell](./user-guide/task-templates/apps/powershell.md) * [Python](./user-guide/task-templates/apps/python.md) * [Survey Variables](./user-guide/task-templates/survey-vars.md) - * [Tasks](./user-guide/tasks.md) - * [Schedules](./user-guide/schedules.md) - * [Key Store](./user-guide/key-store.md) - * [GitLab](./user-guide/key-store/gitlab.md) - * [Inventory](./user-guide/inventory.md) - * [Kerberos](./user-guide/inventory/kerberos.md) - * [NetBox dynamic inventory](./user-guide/netbox-dynamic-inventory.md) - * [Variable Groups](./user-guide/environment.md) - * [Repositories](./user-guide/repositories.md) - * [Bitbucket Access Token](./user-guide/repositories/bitbucket_access_token.md) - * [Integrations](./user-guide/integrations.md) - * [Team](./user-guide/team.md) - + * [Run & monitor](./user-guide/tasks.md) + * [Schedules](./user-guide/schedules.md) + * [Integrations](./user-guide/integrations.md) * [FAQ]() * [Troubleshooting](./faq/troubleshooting.md) diff --git a/src/administration-guide/README.md b/src/administration-guide/README.md index ef79263..aca16eb 100644 --- a/src/administration-guide/README.md +++ b/src/administration-guide/README.md @@ -1,6 +1,8 @@ # Administration Guide -Welcome to the Semaphore UI Administration Guide. This guide provides comprehensive information for installing, configuring, and maintaining your Semaphore instance. +Welcome to the Semaphore UI Administration Guide. This guide provides comprehensive information for installing, configuring, securing, and maintaining your Semaphore instance. + +> Just evaluating or setting up your first project? Start with the [Getting Started](../getting-started/README.md) section before diving into the full administration topics. ## What is Semaphore UI? @@ -35,50 +37,67 @@ This guide will walk you through setting up and managing these features for your ## Quick links -- Installation: [Overview](./installation.md) - - [Package manager](./installation/package-manager.md) - - [Docker](./installation/docker.md) - - [Binary file](./installation/binary-file.md) - - [Kubernetes (Helm chart)](./installation/k8s.md) - - [Cloud](./installation/cloud.md) - - [Snap (deprecated)](./installation/snap.md) - - [Manual installation](./installation_manually.md) -- Configuration: [Overview](./configuration.md) - - [Configuration file](./configuration/config-file.md) - - [Environment variables](./configuration/env-vars.md) - - [Interactive setup](./configuration/cli.md) - - [Snap configuration](./configuration/snap.md) -- Security: [Overview](./security.md) - - [Database security](./security/database.md) - - [Network security](./security/network.md) - - [NGINX config](./security/nginx.md) - - [Apache config](./security/apache.md) - - [Kerberos](./security/kerberos.md) -- Authentication: - - [LDAP](./ldap.md) - - [OpenID](./openid.md) - - [GitHub](./openid/github.md) - - [Google](./openid/google.md) - - [GitLab](./openid/gitlab.md) - - [Gitea](./openid/gitea.md) - - [Authelia](./openid/authelia.md) - - [Authentik](./openid/authentik.md) - - [Keycloak](./openid/keycloak.md) - - [Okta](./openid/okta.md) - - [Azure](./openid/azure.md) - - [Zitadel](./openid/zitadel.md) -- Operations: - - [CLI](./cli.md) - - [Runners](./runners.md) - - [Logs](./logs.md) - - [Notifications](./notifications.md) - - [Email](./notifications/email.md) - - [Telegram](./notifications/telegram.md) - - [Slack](./notifications/slack.md) - - [Teams](./notifications/teams.md) - - [Rocket.Chat](./notifications/rocket.md) - - [DingTalk](./notifications/ding.md) - - [Gotify](./notifications/gotify.md) -- Maintenance: - - [Upgrading](./upgrading.md) - - [Troubleshooting](./troubleshooting.md) +**Plan & Install** + +* Installation: [Overview](./installation.md) + * [Package manager](./installation/package-manager.md) + * [Docker](./installation/docker.md) + * [Binary file](./installation/binary-file.md) + * [Kubernetes (Helm chart)](./installation/k8s.md) + * [Cloud](./installation/cloud.md) + * [Manual installation](./installation_manually.md) + * [Snap (deprecated)](./installation/snap.md) + +**Configure & Harden** + +* Configuration: [Overview](./configuration.md) + * [Configuration file](./configuration/config-file.md) + * [Environment variables](./configuration/env-vars.md) + * [Interactive setup](./configuration/cli.md) + * [Snap configuration](./configuration/snap.md) +* Security: [Overview](./security.md) + * [Database security](./security/database.md) + * [Network security](./security/network.md) + * [NGINX config](./security/nginx.md) + * [Apache config](./security/apache.md) + * [Kerberos](./security/kerberos.md) + +**Authenticate & Authorize** + +* [LDAP](./ldap.md) +* [OpenID](./openid.md) + * [GitHub](./openid/github.md) + * [Google](./openid/google.md) + * [GitLab](./openid/gitlab.md) + * [Gitea](./openid/gitea.md) + * [Authelia](./openid/authelia.md) + * [Authentik](./openid/authentik.md) + * [Keycloak](./openid/keycloak.md) + * [Okta](./openid/okta.md) + * [Azure](./openid/azure.md) + * [Zitadel](./openid/zitadel.md) + +**Integrate & Automate** + +* [Pipelines](./cicd.md) +* [API](./api.md) +* [CLI](./cli.md) + * [Users](./cli/users.md) + * [Vaults](./cli/vaults.md) + * [Runners](./cli/runners.md) + * [Database migrations](./cli/migrations.md) +* [Runners](./runners.md) +* [Logs](./logs.md) +* [Notifications](./notifications.md) + * [Email](./notifications/email.md) + * [Telegram](./notifications/telegram.md) + * [Slack](./notifications/slack.md) + * [Teams](./notifications/teams.md) + * [Rocket.Chat](./notifications/rocket.md) + * [DingTalk](./notifications/ding.md) + * [Gotify](./notifications/gotify.md) + +**Maintain & Recover** + +* [Upgrading](./upgrading.md) +* [Troubleshooting](./troubleshooting.md) diff --git a/src/administration-guide/logs.md b/src/administration-guide/logs.md index 12d1971..d2e528b 100644 --- a/src/administration-guide/logs.md +++ b/src/administration-guide/logs.md @@ -19,6 +19,7 @@ docker logs -f my-semaphore-container ``` This provides a live (streaming) view of the logs. + --- ## Activity log @@ -88,14 +89,10 @@ The Tasks logging options allow you to configure how Semaphore records task exec | `enabled` | `SEMAPHORE_TASK_LOG_ENABLED` | Enable task logging to file. | | `format` | `SEMAPHORE_TASK_LOG_FORMAT` | Log record format. Can be `raw` or `json`. | | `logger` | `SEMAPHORE_TASK_LOG_LOGGER` | [Logger options](#logger-options). | - -#### Task results logging options - -| Parameter | Environment Variables | Description | -| --------------------- | --------------------- | --------------------- | | `result_logger` | `SEMAPHORE_TASK_RESULT_LOGGER` | Logger options. | + #### Logger options | Parameter | Type | Description | @@ -157,11 +154,6 @@ Configure syslog support in `config.json`: } ``` -- `enabled` — turn syslog forwarding on or off. -- `network` — protocol used to reach the collector, such as `udp` or `tcp`. -- `address` — collector address in `host:port` format. -- `tag` — optional identifier prepended to every message. - The same options are available through environment variables if you prefer not to edit the JSON file: ```bash @@ -171,6 +163,16 @@ SEMAPHORE_SYSLOG_ADDRESS=logs.example.com:514 SEMAPHORE_SYSLOG_TAG=semaphore ``` +#### Syslog options + +| Parameter | Environment Variables | Description | +| --------------------- | --------------------- | --------------------- | +| `enabled` | `SEMAPHORE_SYSLOG_ENABLED` | Turn syslog forwarding on or off. | +| `network` | `SEMAPHORE_SYSLOG_NETWORK` | Protocol used to reach the collector, such as `udp` or `tcp`. | +| `address` | `SEMAPHORE_SYSLOG_ADDRESS` | Collector address in `host:port` format. | +| `tag` | `SEMAPHORE_SYSLOG_TAG` | Optional identifier prepended to every message. | + + Restart the Semaphore service after changing these values so that the new syslog destination is applied. ## Summary diff --git a/src/getting-started/README.md b/src/getting-started/README.md new file mode 100644 index 0000000..cadce0b --- /dev/null +++ b/src/getting-started/README.md @@ -0,0 +1,20 @@ +# Getting Started + +New to Semaphore UI? Start here to understand what the platform offers, set up a working environment in minutes, and learn the vocabulary used throughout the rest of the documentation. + +## Who this guide is for + +* **Evaluators** who want to try Semaphore in a lab or proof-of-concept. +* **System administrators** who are planning a production deployment. +* **Automation engineers** who will build and operate projects day-to-day. + +Each subsection is written as a short, self-contained guide that links to deeper administration and user topics when you are ready to dive in. + +## What you will learn + +1. [Quick Start](./quickstart.md) – install Semaphore locally or with Docker and run your first task. +2. [Core Concepts](./concepts.md) – understand the primary building blocks (projects, task templates, inventories, secrets, runners). +3. [UI Tour](./ui-tour.md) – get oriented in the navigation, project dashboards, and execution views. +4. [Next Steps](./next-steps.md) – adopt Semaphore in a team: configure authentication, connect source control, and enforce process. + +> Looking for scripted installs, advanced configuration, or scaling guidance? Skip to the [Administration Guide](../administration-guide/README.md). If you already have Semaphore and need help operating it, check the [User Guide](../user-guide/README.md). diff --git a/src/getting-started/concepts.md b/src/getting-started/concepts.md new file mode 100644 index 0000000..609ac23 --- /dev/null +++ b/src/getting-started/concepts.md @@ -0,0 +1,86 @@ +# Core Concepts + +Semaphore UI groups automation around a few key building blocks. Understanding how they relate makes the rest of the documentation easier to navigate. + +## Projects + +Projects are secure containers for everything your team needs to run automation: repositories, inventories, secrets, runners, and task templates. Each project maintains its own permissions, allowing you to separate teams or environments (for example `Production`, `Staging`, `Sandbox`). + +* Access control is role-based (viewer, operator, admin) and can be delegated per project. +* Integrations such as repositories, keys, and notifications are scoped to the project. +* Activity history shows who ran which tasks and when. + +See the detailed [Projects guide](../user-guide/projects.md). + +## Repositories + +A repository is the source of automation content: Ansible playbooks, Terraform configurations, shell scripts, and more. Semaphore pulls code on demand from Git, local paths, or archive files. + +* Supports HTTPS/SSH Git, Bitbucket, GitLab, GitHub, Gitea, and custom providers. +* Optionally use access keys or deploy keys from the [Key Store](../user-guide/key-store.md). +* Pin branches, tags, or commit SHAs for reproducible runs. + +Learn how to add repositories in the [Repositories guide](../user-guide/repositories.md). + +## Inventories + +Inventories describe the infrastructure or targets your automation will operate on. Semaphore supports: + +* Static inventories defined inline. +* Dynamic inventories fetched from scripts or sources like NetBox. +* Per-project defaults and overrides. + +Inventories are configured under **Inventory**, covered in the [Inventory guide](../user-guide/inventory.md). + +## Task Templates + +Task templates specify what Semaphore runs (e.g. an Ansible playbook, Terraform plan, shell script) and how it runs (repository, inventory, environment variables, surveys, confirmations). + +* Templates support different executors: Ansible, Terraform/OpenTofu, Bash, PowerShell, Python, and more. +* Surveys gather runtime input from operators to avoid hard-coded variables. +* Templates can require manual approval before execution. + +See [Task Templates](../user-guide/task-templates/README.md) for detailed options per executor. + +## Tasks & Schedules + +When you run a task template, Semaphore creates a *task* instance. Tasks record logs, target hosts, outputs, and metadata. + +* Tasks can be triggered manually, via schedules, or through the REST API/CLI. +* Schedule rules support cron-style expressions with timezone awareness. +* Task history is searchable for auditing and troubleshooting. + +Review the [Tasks](../user-guide/tasks.md) and [Schedules](../user-guide/schedules.md) guides to learn more. + +## Secrets & Variables + +Projects keep secrets and configuration data separate from code. Use: + +* **Key Store** for SSH keys, tokens, and credentials. +* **Environment** (variable groups) for runtime variables and secrets exposed as environment variables. +* **Vaults** to store Ansible Vault passwords securely. + +Details live in [Key Store](../user-guide/key-store.md) and [Variable Groups](../user-guide/environment.md). + +## Runners + +Runners execute tasks. By default Semaphore runs tasks on the server host, but you can register additional runners to scale out or isolate workloads. + +* Remote runners connect over gRPC and support labels to target specific workloads. +* Projects can restrict templates to a subset of runners. +* Runner health is visible in the project dashboard and API. + +Learn how to install and manage runners in the [Runners guide](../administration-guide/runners.md). + +## Notifications & Integrations + +Semaphore can notify teams about task outcomes and integrate with chat, email, and webhooks. + +* Built-in connectors include Email, Slack, Microsoft Teams, Telegram, Rocket.Chat, DingTalk, Gotify, and custom webhooks. +* Configure notifications per project or per template. + +See [Notifications](../administration-guide/notifications.md) for configuration steps. + +--- + +Ready to see how these pieces surface in the interface? Continue with the [UI Tour](./ui-tour.md). diff --git a/src/getting-started/next-steps.md b/src/getting-started/next-steps.md new file mode 100644 index 0000000..f33fa15 --- /dev/null +++ b/src/getting-started/next-steps.md @@ -0,0 +1,37 @@ +# Next Steps + +Turn a successful smoke test into a durable deployment. This checklist helps you transition from a local install to a shared production instance. + +## Harden and scale + +1. **Secure transport** – Place Semaphore behind a reverse proxy (NGINX, Apache, Traefik) with TLS. Use our [reverse proxy guides](../administration-guide/security/nginx.md) and [Apache instructions](../administration-guide/security/apache.md). +2. **External database** – Move from the embedded BoltDB to PostgreSQL or MySQL for reliability and backups. Follow the [database configuration guide](../administration-guide/configuration/config-file.md#database-settings). +3. **High availability** – Register additional [runners](../administration-guide/runners.md) to isolate workloads and provide redundancy. Label runners for production vs. staging tasks. + +## Configure authentication and authorization + +1. Integrate with your identity provider using [OpenID Connect](../administration-guide/openid.md) or [LDAP](../administration-guide/ldap.md). +2. Map groups/claims to Semaphore roles so new users inherit the correct access automatically. +3. Define project-level roles (viewer, operator, admin) and limit who can create templates vs. run tasks. + +## Establish automation practices + +1. **Version control** – Store playbooks and infrastructure code in Git. Branch protection keeps production templates stable. +2. **Code reviews** – Use pull requests and testing (lint, syntax) before updating templates. Consider running validation tasks via the [CLI](../administration-guide/cli.md) or CI pipelines. +3. **Secrets management** – Rotate keys in the [Key Store](../user-guide/key-store.md), use environment variables for non-secret configuration, and document ownership. + +## Operationalize monitoring and alerts + +1. Set up [notifications](../administration-guide/notifications.md) for critical projects (Slack, Teams, email, etc.). +2. Export logs to your observability stack or enable structured logging via configuration flags. +3. Define on-call or escalation procedures backed by Semaphore task history. + +## Document and train + +1. Capture the workflow for creating new projects or templates. Link your runbooks directly to relevant sections in the [User Guide](../user-guide/README.md). +2. Share the [UI Tour](./ui-tour.md) with operators so they build confidence quickly. +3. Encourage teams to contribute to this documentation. mdBook makes it easy to submit pull requests with updates. + +--- + +Need help? Join the [Discord community](https://discord.gg/5R6k7hNGcH) or open an issue on [GitHub](https://github.com/semaphoreui/semaphore) to discuss best practices with the maintainers and community. diff --git a/src/getting-started/quickstart.md b/src/getting-started/quickstart.md new file mode 100644 index 0000000..c055f7b --- /dev/null +++ b/src/getting-started/quickstart.md @@ -0,0 +1,74 @@ +# Quick Start + +Follow this walkthrough to get Semaphore UI running on your workstation and execute a simple automation task. The steps take around 10–15 minutes and require no prior knowledge of the platform. + +## 1. Pick an install method + +Choose the option that best fits your environment: + +| When to use | Recommended guide | +| --- | --- | +| You want an isolated test environment in minutes | [Docker install](../administration-guide/installation/docker.md) +| You prefer native binaries and system integration | [Binary install](../administration-guide/installation/binary-file.md) +| You run on Kubernetes and want to evaluate at cluster scale | [Helm chart](../administration-guide/installation/k8s.md) + +> Need another option (package manager, cloud images, manual install)? See the full [Installation overview](../administration-guide/installation.md). + +After installation, run the `semaphore` binary (or container) and browse to `http://localhost:3000` to complete the initial setup wizard. + +## 2. Complete the setup wizard + +Semaphore walks you through the steps below: + +1. Create the first administrator user. +2. Provide database connection details. +3. Generate or supply an encryption key (used for secrets). +4. Confirm SMTP settings if you want email alerts. You can skip this for a quick evaluation. + +The wizard produces a configuration file on disk. You can always adjust it later using the [configuration reference](../administration-guide/configuration.md). + +## 3. Create a sandbox project + +Once you sign in, create a project to hold your automation assets: + +1. Go to **Projects → New Project**. +2. Give it a name like `Demo Project` and keep the default repository and inventory settings. +3. After the project opens, note the tabs across the top: **Task Templates**, **Tasks**, **Schedules**, **Access Keys**, **Repositories**, **Inventory**, and **Environment**. + +Projects let you scope permissions and integrations. Learn more in the [Projects overview](../user-guide/projects.md). + +## 4. Add a repository and key + +You can use any Git repository with an Ansible playbook or shell script. For a quick test, use a public sample playbook. + +1. Navigate to **Repositories → Add Repository**. +2. Select `Git`, paste the repository URL (for example, `https://github.com/semaphoreui/semaphore-demo`), and save. +3. If the repository is private, create an access key under **Key Store** and reference it here. Keys and tokens are encrypted at rest; see [Key Store](../user-guide/key-store.md). + +## 5. Define a task template + +Task templates describe what Semaphore will run. + +1. Open **Task Templates → New Template**. +2. Choose **Ansible Playbook** (or another executor you prefer). +3. Select the repository and playbook path (e.g. `site.yml`). +4. Pick an inventory (the default `Static Inventory` works for local demos) and click **Create**. + +Read more in the [Task Templates guide](../user-guide/task-templates/README.md). + +## 6. Run and inspect the task + +1. In the template list, click **Run**. +2. Provide optional variables or confirmations, then start the task. +3. Observe the live output and status indicators. +4. After completion, review the log, duration, and host results. You can download logs or re-run from the same page. + +The [Tasks guide](../user-guide/tasks.md) explains status codes, log retention, and re-run behavior. + +## 7. Keep going + +You now have a functioning Semaphore environment. Continue with: + +* [Core Concepts](./concepts.md) to understand how projects, inventories, templates, and permissions fit together. +* [UI Tour](./ui-tour.md) for a guided walkthrough of navigation, filters, and dashboards. +* [Next Steps](./next-steps.md) to move from a sandbox to a shared or production deployment. diff --git a/src/getting-started/ui-tour.md b/src/getting-started/ui-tour.md new file mode 100644 index 0000000..173a4d8 --- /dev/null +++ b/src/getting-started/ui-tour.md @@ -0,0 +1,69 @@ +# UI Tour + +This guided tour highlights the primary areas of Semaphore UI so you can quickly find the features you need. Screens may look slightly different depending on your version, theme, or feature flags, but the navigation stays consistent. + +## Global navigation + +The top-level navigation bar includes: + +* **Projects** – all projects you can access. Pin frequently used projects to the sidebar. +* **Administration** – system-wide settings (available to administrators only), including user management, runners, license information, and system diagnostics. +* **Help** – links to documentation, community resources, and version information. + +Use the profile menu (top right) to update your account details, configure notification preferences, or sign out. + +## Project dashboard + +Opening a project lands you on the **Task Templates** view by default. The project header contains: + +* Project information: name, description, default environment. +* Quick stats: recent task success/failure and queued runs. +* Tabs for resources within the project. + +Tabs available in every project: + +| Tab | Purpose | +| --- | --- | +| Task Templates | Define what Semaphore runs, configure surveys, matrices, approvals. | +| Tasks | Monitor historical and in-flight task executions. Filters support status, authors, templates, and time ranges. | +| Schedules | Automate recurring runs with cron-like rules. | +| Repositories | Manage source control integrations and ref selections. | +| Inventory | Configure static or dynamic inventories used by templates. | +| Environment | Define variable groups exposed to tasks. | +| Key Store | Store SSH keys, API tokens, passwords, vault secrets. | +| Team | Invite users and assign roles (viewer, operator, admin). | + +Some projects display extra tabs (for example **Runners** or **Integrations**) when features are enabled. + +## Task details view + +Clicking a task opens a detailed execution view: + +* **Summary panel** shows status, duration, initiator, runner, commit SHA, and inventory. +* **Live log** streams output in real time with search and download options. +* **Hosts/Steps tabs** break down playbook results or Terraform steps. +* **Artifacts** lists generated files or state snapshots where applicable. +* **Actions menu** lets you rerun, cancel, or clone the task (depending on permissions). + +Use the breadcrumb trail to jump back to the originating template or project dashboard. + +## Administration area + +Administrators gain a system-level sidebar: + +* **Users & Teams** – manage global accounts, SSO mapping, and roles. +* **Runners** – view registered runners, labels, versions, and last-seen status. +* **System** – check version, license state (if applicable), background job queues, and telemetry. +* **Settings** – configure global options such as OpenID providers, SMTP, audit retention, or feature flags. + +Most settings link directly to detailed instructions in the [Administration Guide](../administration-guide/README.md). + +## Keyboard and productivity tips + +* Press `Ctrl/⌘ + K` to open the command palette for quick navigation. +* Use saved filters on the **Tasks** view to monitor specific templates or teams. +* Pin projects to the left sidebar by clicking the star icon next to their name. + +--- + +Next, review [Next Steps](./next-steps.md) to turn your evaluation into a repeatable, collaborative setup. diff --git a/src/user-guide/README.md b/src/user-guide/README.md index eabfe9a..b04e5f3 100644 --- a/src/user-guide/README.md +++ b/src/user-guide/README.md @@ -4,40 +4,47 @@ Learn how to use Semaphore day-to-day: create projects, run tasks, manage invent ## Start here -- Organize work with projects and teams -- Connect repositories and key store -- Define inventories and variable groups -- Create task templates and run tasks on schedule - -## Quick links - -- Projects: [Overview](./projects.md) - - [History](./projects/history.md) - - [Activity](./projects/activity.md) - - [Settings](./projects/settings.md) - - [Runners (Pro)](./projects/runners.md) -- Tasks and schedules: - - [Tasks](./tasks.md) - - [Schedules](./schedules.md) -- Task Templates: [Overview](./task-templates/README.md) - - [Ansible](./task-templates/apps/ansible.md) - - [Terraform/OpenTofu](./task-templates/apps/terraform.md) - - [Workspaces](./task-templates/apps/terraform/workspaces.md) - - [HTTP Backend (Pro)](./task-templates/apps/terraform/states.md) - - [Shell/Bash scripts](./task-templates/apps/bash.md) - - [PowerShell](./task-templates/apps/powershell.md) - - [Python](./task-templates/apps/python.md) - - [Survey Variables](./task-templates/survey-vars.md) -- Variables and secrets: - - [Variable Groups](./environment.md) - - [Key Store](./key-store.md) - - [GitLab](./key-store/gitlab.md) -- Inventory: - - [Inventory](./inventory.md) - - [Kerberos](./inventory/kerberos.md) - - [NetBox dynamic inventory](./netbox-dynamic-inventory.md) -- Repositories: - - [Repositories](./repositories.md) - - [Bitbucket Access Token](./repositories/bitbucket_access_token.md) -- Integrations: [Overview](./integrations.md) -- Team management: [Overview](./team.md) +1. [Organize work](./projects.md) – create projects, manage access, and review activity. +2. [Connect resources](./repositories.md) – add code, inventories, variables, and secrets. +3. [Build automation](./task-templates/README.md) – create task templates for Ansible, Terraform/OpenTofu, scripts, and more. +4. [Run & monitor](./tasks.md) – execute tasks, schedule repeats, and integrate notifications. + +## Quick links by workflow + +**Organize work** + +* Projects: [Overview](./projects.md) + * [History](./projects/history.md) + * [Activity](./projects/activity.md) + * [Settings](./projects/settings.md) + * [Runners (Pro)](./projects/runners.md) +* Team management: [Overview](./team.md) + +**Connect resources** + +* Repositories: [Overview](./repositories.md) + * [Bitbucket Access Token](./repositories/bitbucket_access_token.md) +* Inventory: [Overview](./inventory.md) + * [Kerberos](./inventory/kerberos.md) + * [NetBox dynamic inventory](./netbox-dynamic-inventory.md) +* Variable Groups: [Overview](./environment.md) +* Key Store: [Overview](./key-store.md) + * [GitLab](./key-store/gitlab.md) + +**Build automation** + +* Task Templates: [Overview](./task-templates/README.md) + * [Ansible](./task-templates/apps/ansible.md) + * [Terraform/OpenTofu](./task-templates/apps/terraform.md) + * [Workspaces](./task-templates/apps/terraform/workspaces.md) + * [HTTP Backend (Pro)](./task-templates/apps/terraform/states.md) + * [Shell/Bash scripts](./task-templates/apps/bash.md) + * [PowerShell](./task-templates/apps/powershell.md) + * [Python](./task-templates/apps/python.md) + * [Survey Variables](./task-templates/survey-vars.md) + +**Run & monitor** + +* Tasks: [Overview](./tasks.md) +* Schedules: [Overview](./schedules.md) +* Integrations: [Overview](./integrations.md)