{"id":21313953,"url":"https://github.com/octopusdeploy/calamari","last_synced_at":"2025-04-04T23:08:17.187Z","repository":{"id":27909485,"uuid":"31401355","full_name":"OctopusDeploy/Calamari","owner":"OctopusDeploy","description":"| Public |  The core deployment scripts and tools used by Octopus Deploy","archived":false,"fork":false,"pushed_at":"2024-10-29T22:07:17.000Z","size":83993,"stargazers_count":13,"open_issues_count":41,"forks_count":110,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-10-30T00:39:21.698Z","etag":null,"topics":["public"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OctopusDeploy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-27T03:16:02.000Z","updated_at":"2024-10-29T03:09:30.000Z","dependencies_parsed_at":"2023-10-11T02:44:40.280Z","dependency_job_id":"620ce747-acfd-4a48-96e6-3e47d44e8272","html_url":"https://github.com/OctopusDeploy/Calamari","commit_stats":null,"previous_names":[],"tags_count":838,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FCalamari","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FCalamari/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FCalamari/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2FCalamari/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OctopusDeploy","download_url":"https://codeload.github.com/OctopusDeploy/Calamari/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261604,"owners_count":20910108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["public"],"created_at":"2024-11-21T18:09:27.154Z","updated_at":"2025-04-04T23:08:17.160Z","avatar_url":"https://github.com/OctopusDeploy.png","language":"C#","readme":"Calamari is the command-line tool invoked by Tentacle during a deployment. It knows how to extract and install NuGet packages, run the Deploy.ps1 etc. conventions, modify configuration files, and all the other things that happen during a deployment.\n\n## Building\n\nYou will need the .NET SDK `6.0`, downloadable from https://dotnet.microsoft.com/download\n\nRun `Build-Local.ps1` or `Build-Local.sh` to build the solution locally.\n\nWhen the solution is built, several new Calamari nuget packages are created in the `artifacts` directory.\n\n\u003e **For Octopus Developers:**\n\u003e \n\u003eThe `Build-Local` scripts will also copy the nuget packages to the LocalPackages folder which can be\nfound in the same parent folder as the Calamari repo. If the Octopus Server repo exists in the same \nparent folder, `Build-Local` will also update the Octopus.Server.csproj to reference the Calamari \nversion produced by the build. This means that you can simply rebuild Server locally to test the new\nversion of Calamari.\n\u003e\n\u003efolder structure example:\n\u003e```\n\u003edev\\\n\u003e    Calamari\\\n\u003e    LocalPackages\\ \n\u003e OctopusDeploy\\\n\u003e```\n\n## Usage\n\n\u003e **Octopus Server 2020.3+: Using a custom version of Calamari may not work**\n\u003e\n\u003e Calamari is currently being filleted into [Sashimi](https://github.com/OctopusDeploy/Sashimi). Due to the architectural changes involved in this transformation, using a custom version of Calamari with Octopus Server version 2020.3+ may not work. Please get in touch with support@octopus.com if this affects you, to help us make decisions about how we can support custom implementations of deployment steps.\n\nTo use your own Calamari package with an Octopus 3.0 server, run the following commands\n```\nOctopus.Server.exe service --instance \u003cinstance\u003e --stop --nologo --console\nOctopus.Server.exe configure --instance \u003cinstance\u003e --customBundledPackageDirectory=\u003cdirectory\u003e --nologo --console\nOctopus.Server.exe service --instance \u003cinstance\u003e --start --nologo --console\n```\n\nwhere `\u003cdirectory\u003e` is the directory containing the `Calamari.*.nupkg` files. If your server is setup as the default instance, you may ommit the `--instance \u003cinstance\u003e` parameter.\n\nThis will add the following setting to your Octopus Server configuration file:\n\n```\n  \u003cset key=\"Octopus.Deployment.CustomBundledPackageDirectory\"\u003eC:\\GitHub\\Calamari\\built-packages\u003c/set\u003e\n```\n\nThe exe and configuration file can normally be found at:\n\n```\nC:\\Octopus\\OctopusServer\\OctopusServer.config\n```\n\nIf you want to revert to the bundled package, run the following commands\n```\nOctopus.Server.exe service --instance \u003cinstance\u003e --stop --nologo --console\nOctopus.Server.exe configure --instance \u003cinstance\u003e --customBundledPackageDirectory= --nologo --console\nOctopus.Server.exe service --instance \u003cinstance\u003e --start --nologo --console\n```\n\n** Ensure you update your build to the latest Calamari or revert to the bundled package when you upgrade Octopus Server **\n\n## Releasing\n\nAfter you finish merging to main to tag the Calamari NuGet package:\n\nFirstly, find out what the latest tag is. There are two ways to do this:\n\n* On your terminal, checkout `main` and `git pull` for good measure\n* Run `git tag` and scroll to the bottom of the list to get the last known tag\n\nAlternatively,\n\n* Check the last build on main as it will be pre-release version of the next `\u003cMajor\u003e.\u003cMinor\u003e.\u003cPatch\u003e` version\n\nFinally, tag and push the new release\n\n* Patch, Minor or Major Version the tag according to `\u003cMajor\u003e.\u003cMinor\u003e.\u003cPatch\u003e`\n* `git push origin \u003cMajor\u003e.\u003cMinor\u003e.\u003cPatch\u003e` to push your newly created tag to Github.\n\n\u003e [!WARNING]\n\u003e Avoid using `git push --tags` as it will push all of your local tags to the remote repository.  \n\u003e This is not recommended as it can cause confusion and potential issues with the build server when it attempts to calculate the release version number due to the potential of unexpected tags being pushed.\n\nThis will trigger our build server to build and publish a new version to feedz.io which can be seen here https://feedz.io/org/octopus-deploy/repository/dependencies/packages/Calamari.\n\n## Debugging\n\nOption 1 is recommended if you can use the default worker.\n\n### Option 1: Reference local binary\n1. Build Calamari in your IDE\n2. Get the path to the executable (The one directly in the bin folder for the Calamari project for the flavour you want to debug e.g. `Calamari` or `Calamari.AzureAppService` with no extension for macOS and Linux, `Calamari.exe` or `Calamari.AzureAppService.exe` for Windows)\n3. In Octopus, set an unscoped variable `Octopus.Calamari.Executable` to the full path to the executable. This is set per project.\n4. Now when you run a deployment it will use your debug build.\n\n#### Benefits:\n- Extremely fast iteration, you don’t need to stop server between Calamari builds.\n- It does not exercise the full deployment functionality of checking calamari versions etc (most of the time, this does not matter).\n\n#### Drawbacks:\n- You must run the step on your machine (default worker) - basically the executable has to be at the path on whatever machine is executing the step. This is a problem when working with Kubernetes Tentacle for example.\n\n### Option 2: Package Calamari into your server build\n1. In terminal, run `./build-local.sh` (build-local.ps1 is available for Windows)\n2. Nuke will build and package up Calamari then it will update the `Calamari.Consolidated` version in your `Octopus.Server.csproj`\n3. Restart Server to force a rebuild with the new version of Calamari.\n\n\u003e Note: You must have a local nuget feed setup for the path `../LocalPackages` relative to this repo\n\u003e\n\u003e eg. `dotnet nuget add source -n local ~/path/to/LocalPackages`\n\n#### Benefits:\n- It uses the “proper” mechanism to deploy Calamari.\n- You can use it when you’re using a remote worker.\n\n#### Drawbacks:\n- It takes ~10 minutes to build and pack Calamari, however you can reduce this significantly by targeting a specific runtime/framework if you don't need the rest\n    - eg `./build-local.sh -y --framework \"net6.0\" --runtime \"linux-x64\"`\n- You need to restart Server for Calamari changes to take effect\n\n### Bonus Variables!\n- Set `Octopus.Calamari.WaitForDebugger` to `True` to get a debug version of Calamari to wait for a Debugger to be attached before continuing. The log message from Calamari will show it’s waiting for the debugger and it will give the PID to use when you’re looking to attach.\n- Set `OctopusPrintEvaluatedVariables` to `True` to get all variables that are sent to Calamari, printed to the verbose long when executing a step.\n\n\u003e Tip: Creating a variable set with your configuration makes it easy to toggle this behaviour per project\n\n## Testing:\n\nMany of the tests require credentials for accessing external services.\nThese credentials can be provided via environment variables, or read from OctopusDeploy's 1Password repository.\nThere are two environment variables which define how credentials are provided:\n* CALAMARI__Tests__SecretManagerEnabled - if true, read from 1password; if false read from environment variables\n* CALAMARI__Tests__SecretManagerAccount - if set defines the account to use. If unset, defaults to \"octopusdeploy.1password.com\"\n\nTo use the 1password integration you are required to have installed:\n* 1Password application, and associated\n* 1Password cli application (op)\n\nFor details on their configuration see the [README.md](https://github.com/OctopusDeploy/1password-sdk/blob/main/README.md) in the 1password-sdk repository\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Fcalamari","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctopusdeploy%2Fcalamari","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Fcalamari/lists"}