# winch

> winch is a server configuration tool. It describes the desired state of your servers in declarative YAML and provides commands to manage that state.

The source code is at https://github.com/davidklassen/winch. All docs pages in one file: https://winchstack.app/llms-full.txt

## Docs

- [Dead simple server configuration tool](https://winchstack.app/index.md): winch is a server configuration tool. It describes the desired state of your servers in declarative YAML and provides commands to manage that state.
- [Quick Start](https://winchstack.app/docs/index.md): Install winch, and write the message of the day on your server.

## User Guide

- [User Guide](https://winchstack.app/docs/user-guide/index.md): Build a web server with a firewall, a static site, and HTTPS, and learn winch on the way.
- [Start a project](https://winchstack.app/docs/user-guide/start/index.md): Make the project file, and run a first command on the server.
- [A web server](https://winchstack.app/docs/user-guide/web-server/index.md): Install nginx behind a firewall, read the plan, and apply it.
- [Environments](https://winchstack.app/docs/user-guide/environments/index.md): Add a staging server with its own inventory, and test changes there before production.
- [Groups and pipelines](https://winchstack.app/docs/user-guide/groups-and-pipelines/index.md): Add a database server, and run different steps on servers with different roles.
- [Recipes](https://winchstack.app/docs/user-guide/recipes/index.md): Move the nginx steps into a recipe, and serve the site from its own config.
- [HTTPS](https://winchstack.app/docs/user-guide/https/index.md): Get a certificate from Let's Encrypt, and serve the site over HTTPS.

## Reference

- [Reference](https://winchstack.app/docs/reference/index.md): The commands, the topics, and the modules of winch.

## Commands

- [Commands](https://winchstack.app/docs/reference/commands/index.md): The commands of winch, their usage, and their flags.
- [winch](https://winchstack.app/docs/reference/commands/winch/index.md): winch is a server configuration tool. It describes the desired state of your servers in declarative YAML and provides commands to manage that state.
- [winch validate](https://winchstack.app/docs/reference/commands/validate/index.md): check the project without contacting a host
- [winch fmt](https://winchstack.app/docs/reference/commands/fmt/index.md): format the project files
- [winch plan](https://winchstack.app/docs/reference/commands/plan/index.md): show the changes that apply would make
- [winch apply](https://winchstack.app/docs/reference/commands/apply/index.md): make the changes after you approve the plan
- [winch run](https://winchstack.app/docs/reference/commands/run/index.md): plan and apply one module step
- [winch exec](https://winchstack.app/docs/reference/commands/exec/index.md): run a shell command on hosts
- [winch secret](https://winchstack.app/docs/reference/commands/secret/index.md): manage secrets and the age key
- [winch secret init](https://winchstack.app/docs/reference/commands/secret-init/index.md): add an age key to the recipients
- [winch secret generate](https://winchstack.app/docs/reference/commands/secret-generate/index.md): make a random password as a secret
- [winch secret encrypt](https://winchstack.app/docs/reference/commands/secret-encrypt/index.md): encrypt a value from stdin or a prompt as a secret
- [winch secret decrypt](https://winchstack.app/docs/reference/commands/secret-decrypt/index.md): print the plaintext of a secret
- [winch secret rekey](https://winchstack.app/docs/reference/commands/secret-rekey/index.md): encrypt all secrets again
- [winch doc](https://winchstack.app/docs/reference/commands/doc/index.md): show the reference
- [winch version](https://winchstack.app/docs/reference/commands/version/index.md): print the version and the platform

## Project files

- [Project files](https://winchstack.app/docs/reference/project-files/index.md): project, inventory, pipeline, recipe, step, handlers
- [project](https://winchstack.app/docs/reference/project-files/project/index.md): project files and directories
- [inventory](https://winchstack.app/docs/reference/project-files/inventory/index.md): hosts and groups
- [pipeline](https://winchstack.app/docs/reference/project-files/pipeline/index.md): ordered stages that apply steps to hosts
- [recipe](https://winchstack.app/docs/reference/project-files/recipe/index.md): reusable groups of steps
- [step](https://winchstack.app/docs/reference/project-files/step/index.md): keys that every step has
- [handlers](https://winchstack.app/docs/reference/project-files/handlers/index.md): steps that run after a change

## Values

- [Values](https://winchstack.app/docs/reference/values/index.md): variables, templates, expressions, facts, secrets
- [variables](https://winchstack.app/docs/reference/values/variables/index.md): named values for hosts, groups, and recipes
- [templates](https://winchstack.app/docs/reference/values/templates/index.md): text with values filled in (!tpl)
- [expressions](https://winchstack.app/docs/reference/values/expressions/index.md): computed values (!expr)
- [facts](https://winchstack.app/docs/reference/values/facts/index.md): values that winch reads from each host
- [secrets](https://winchstack.app/docs/reference/values/secrets/index.md): encrypted values in the project

## Running

- [Running](https://winchstack.app/docs/reference/running/index.md): workflow, remote
- [workflow](https://winchstack.app/docs/reference/running/workflow/index.md): how to plan and apply changes
- [remote](https://winchstack.app/docs/reference/running/remote/index.md): how winch reaches a host and runs there

## Modules

- [Modules](https://winchstack.app/docs/reference/modules/index.md): The modules of winch, their keys, and examples.
- [assert](https://winchstack.app/docs/reference/modules/assert/index.md): stop a host when a check command fails
- [certbot](https://winchstack.app/docs/reference/modules/certbot/index.md): get a Let's Encrypt certificate
- [cmd](https://winchstack.app/docs/reference/modules/cmd/index.md): run a command
- [debconf](https://winchstack.app/docs/reference/modules/debconf/index.md): set a debconf answer
- [dir](https://winchstack.app/docs/reference/modules/dir/index.md): manage a directory
- [download](https://winchstack.app/docs/reference/modules/download/index.md): download a file or an archive
- [file](https://winchstack.app/docs/reference/modules/file/index.md): manage a file
- [firewall](https://winchstack.app/docs/reference/modules/firewall/index.md): filter incoming traffic
- [group](https://winchstack.app/docs/reference/modules/group/index.md): manage a group
- [hostname](https://winchstack.app/docs/reference/modules/hostname/index.md): set the host name
- [line](https://winchstack.app/docs/reference/modules/line/index.md): manage one line in a file
- [link](https://winchstack.app/docs/reference/modules/link/index.md): manage a symbolic link
- [pkg](https://winchstack.app/docs/reference/modules/pkg/index.md): install or remove packages
- [reboot](https://winchstack.app/docs/reference/modules/reboot/index.md): reboot the host
- [repo](https://winchstack.app/docs/reference/modules/repo/index.md): manage an apt source
- [service](https://winchstack.app/docs/reference/modules/service/index.md): control a systemd unit
- [timezone](https://winchstack.app/docs/reference/modules/timezone/index.md): set the time zone
- [unit](https://winchstack.app/docs/reference/modules/unit/index.md): manage a systemd unit file
- [upgrade](https://winchstack.app/docs/reference/modules/upgrade/index.md): upgrade the installed packages
- [user](https://winchstack.app/docs/reference/modules/user/index.md): manage a user account