{"id":21995357,"url":"https://github.com/blinklabs-io/cardano-up","last_synced_at":"2025-04-30T17:27:09.608Z","repository":{"id":220823543,"uuid":"750867157","full_name":"blinklabs-io/cardano-up","owner":"blinklabs-io","description":"Command line utility for managing Cardano services","archived":false,"fork":false,"pushed_at":"2025-04-21T05:39:40.000Z","size":625,"stargazers_count":23,"open_issues_count":16,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-23T11:18:56.027Z","etag":null,"topics":["cardano","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blinklabs-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-31T13:35:47.000Z","updated_at":"2025-04-18T14:48:19.000Z","dependencies_parsed_at":"2024-02-21T23:32:43.203Z","dependency_job_id":"cd5d9da6-5a19-4807-bb1e-6a3dcc65e15c","html_url":"https://github.com/blinklabs-io/cardano-up","commit_stats":{"total_commits":209,"total_committers":6,"mean_commits":"34.833333333333336","dds":0.6698564593301435,"last_synced_commit":"64a3d735b725976ef1a27effaee9b81598866ebe"},"previous_names":["blinklabs-io/cardano-up"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-up","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-up/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-up/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blinklabs-io%2Fcardano-up/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blinklabs-io","download_url":"https://codeload.github.com/blinklabs-io/cardano-up/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251750489,"owners_count":21637732,"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":["cardano","go","golang"],"created_at":"2024-11-29T21:14:27.122Z","updated_at":"2025-04-30T17:27:09.594Z","avatar_url":"https://github.com/blinklabs-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cardano-up\n\n## Installation\n\n### Install latest release (recommended)\n\nYou can download the latest releases from the [Releases page](https://github.com/blinklabs-io/cardano-up/releases).\nPlace the downloaded binary in `/usr/local/bin`, `~/.local/bin`, or some other convenient location and make sure\nthat location has been added to your `$PATH`. Our recommendation is to use `~/.local/bin` as that is where this\ntool will install wrapper scripts.\n\nNOTE: On MacOS, you will need to allow `/` to be used by Docker Desktop\n\n## Basic usage\n\n### List available packages\n\n```\ncardano-up list-available\n```\n\n### Install a package and interact with it\n\nAdd `~/.local/bin` to your `$PATH` by adding the following to your shell RC/profile to make any\ncommands/scripts installed readily available\n\n```\nexport PATH=~/.local/bin:$PATH\n```\n\nInstall cardano-node\n\n```\ncardano-up install cardano-node\n```\n\nYou can also add any env vars exported by the installed packages to your env by adding the following to your shell RC/profile:\n\n```\neval $(cardano-up context env)\n```\n\nYou should now be able to run `cardano-cli` normally.\n\n```\ncardano-cli query tip --testnet-magic 2\n```\n\n### Uninstall a package\n\n```\ncardano-up uninstall cardano-node\n```\n\n### Enabling shell auto-complete\n\nEnable for current session:\n\n```\nsource \u003c(cardano-up completion bash)\n```\n\nEnable for all future sessions:\n\n```\ncardano-up completion bash \u003e /etc/bash_completion.d/cardano-up\n```\n\n## Contexts\n\nContexts are used to allow you to install multiple copies of the same package with different network configurations side by side. They allow you to do things\nsuch as running a `preprod` and `mainnet` Cardano node on the same machine, or even have multiple `preview` Cardano node instances running different versions\nof the node.\n\nCommands such as `install`, `uninstall`, and `list` work in the active context. You can use the `context` command to change the active context or manage available contexts.\n\n## Command reference\n\nThe `cardano-up` command consists of multiple subcommands. You can list all subcommands by running `cardano-up` with no arguments or with the `--help` option.\n\n```\n$ cardano-up\nUsage:\n  cardano-up [command]\n\nAvailable Commands:\n  completion     Generate the autocompletion script for the specified shell\n  context        Manage the current context\n  down           Stops all Docker containers\n  help           Help about any command\n  info           Show info for an installed package\n  install        Install package\n  list           List installed packages\n  list-available List available packages\n  logs           Show logs for an installed package\n  uninstall      Uninstall package\n  up             Starts all Docker containers\n  update         Update the package registry cache\n  upgrade        Upgrade package\n  validate       Validate package file(s) in the given directory\n  version        Displays the version\n\nFlags:\n  -D, --debug   enable debug logging\n  -h, --help    help for cardano-up\n  -v, --verbose Show all available versions of packages\n\nUse \"cardano-up [command] --help\" for more information about a command.\n```\n\n### `completion`\n\nThe `completion` subcommand generates shell auto-completion configuration for various supported shells. Run `completion help \u003cshell\u003e` for more information on installing completion support for your shell.\n\n### `context`\n\nThe `context` subcommand manages contexts. It has subcommands of its own for the various context-related functions.\n\n#### `context create`\n\nCreate a new context with a given name, optionally specifying a description and a Cardano network\n\n#### `context delete`\n\nDelete the context with the given name, if it exists\n\n#### `context env`\n\nOutput environment variables for the active context\n\n#### `context list`\n\nLists the available contexts\n\n#### `context select`\n\nSets the active context to the given context name\n\n### `down`\n\nStops all running services for packages in the active context\n\n### `help`\n\nDisplays usage information for commands and subcommands\n\n### `info`\n\nShows information for an installed package, including the name, version, context name, any post-install notes, etc.\n\n### `install`\n\nInstalls the specified package, optionally setting the network for the active context\n\n### `list`\n\nLists installed packages in the active context, or all contexts with `-A`\n\n### `list-available`\n\nBy default `list-available` lists only the latest version of each package available for install.\nUse the `--verbose` or `(-v)` flag to display all available versions of each package.\n\n### `logs`\n\nDisplays logs from a running service for the specified package in the active context\n\n### `uninstall`\n\nUninstalls the specified package in the active context\n\n### `up`\n\nStarts all services for packages in the active context\n\n### `update`\n\nForce a refresh of the package registry cache\n\n### `upgrade`\n\nUpgrade the specified package\n\n### `validate`\n\nValidates packages defined in specified path\n\n### `version`\n\nDisplays the version\n\n## Development\n\n### Install from source\n\nBefore starting, make sure that you have at least Go 1.21 installed locally. Run the following\nto download the latest source code and build.\n\n```\ngo install github.com/blinklabs-io/cardano-up/cmd/cardano-up@main\n```\n\nOnce that completes, you should have a `cardano-up` binary in `~/go/bin`.\n\n```\n$ ls -lh ~/go/bin/cardano-up\n-rwxrwxr-x 1 agaffney agaffney 16M Mar 16 08:13 /home/agaffney/go/bin/cardano-up\n```\n\nYou may need to add a line like the following to your shell RC/profile to update your PATH\nto be able to find the binary.\n\n```\nexport PATH=~/go/bin:$PATH\n```\n\n### Compile from source\n\nThere is a Makefile (you will need `make` installed) which you can invoke.\n\n```bash\nmake\n```\n\nThis will create a `cardano-up` binary in the repository root.\n\n### Creating and maintaining packages\n\nPackages and their versions are defined under `packages/` in this repo. Each separate package name has its own subdirectory,\nand each version of a particular package is defined in a separate file under that subdirectory. For example, package `foo` with\nversion `1.2.3` would live in `packages/foo/foo-1.2.3.yaml`.\n\n#### Testing local changes to packages\n\nThe remote package repo will be used by default when running `cardano-up`. To instead use the package files in a local directory, you\ncan run it like:\n\n```bash\nREGISTRY_DIR=packages/ cardano-up ...\n```\n\n#### Validating package files\n\nThere is a built-in subcommand for validating package files. It will be run automatically for a PR, but you can also run it manually.\n\n```bash\ncardano-up validate packages/\n```\n\n#### Templating\n\nPackage manifest files are evaluated as a Go template before being parsed as YAML. The following values are available for use in templates.\n\n| Name | Description |\n| --- | --- |\n| `.Package` | |\n| `.Package.Name` | Full package name including the version |\n| `.Package.ShortName` | Package name |\n| `.Package.Version` | Package version |\n| `.Package.Options` | Provided package options |\n| `.Paths` | |\n| `.Paths.BinDir` | Binary dir for package |\n| `.Paths.CacheDir` | Cache dir for package |\n| `.Paths.ContextDir` | Context dir for package |\n| `.Paths.DataDir` | Data dir for package |\n| `.Ports` | Container port mappings |\n\n#### Package manifest format\n\nThe package manifest format is a YAML file with the following fields:\n\n| Field | Required | Description |\n| --- | :---: | --- |\n| `name` | x | Package name. This must match the prefix of the package manifest filename and the parent directory name |\n| `version` | x | Package version |\n| `description` | | Package description |\n| `preInstallScript` | | Arbitrary command that will be run before the package is installed |\n| `postInstallScript` | | Arbitrary command that will be run after the package is installed |\n| `preUninstallScript` | | Arbitrary command that will be run before the package is uninstalled |\n| `postUninstallScript` | | Arbitrary command that will be run after the package is uninstalled |\n| `installSteps` | | Steps to install package |\n| `dependencies` | | Dependencies for the package |\n| `tags` | | Tags for the package |\n| `options` | | Install-time options |\n| `outputs` | | Package outputs |\n\n##### `installSteps`\n\nThe install steps for a package consist of a list of resources to manage. They are applied in order on install and reverse order on uninstall.\n\nEach install step may contain a condition that will make it's evaluation optional. A condition will be implicitly wrapped in `{{ if ` and ` }}True{{ else }}False{{ end }}` and evaluated by the templating engine.\n\n###### `docker`\n\nThe `docker` install step type manages a Docker container.\n\nExample:\n\n```yaml\ninstallSteps:\n  - docker:\n      containerName: nginx\n      image: nginx\n```\n\n| Field | Required | Description |\n| --- | :---: | --- |\n| `containerName` | x | Name of the container to create. This will be automatically prefixed by the package name |\n| `image` | x | Docker image to use for container |\n| `env` | | Environment variables for container (expects a map) |\n| `command` | | Override container command (expects a list) |\n| `args` | | Override container args (expects a list) |\n| `binds` | | Volume binds in the Docker `-v` flag format (expects a list) |\n| `ports` | | Ports to map in the Docker `-p` flag format (expects a list). NOTE: assigning a static port mapping may cause conflicts |\n| `pullOnly` | | Only pull the image to pre-fetch it (expects a bool, defaults to creating container) |\n\n###### `file`\n\nThe `file` install step type manages a file.\n\nExample:\n\n```yaml\ninstallSteps:\n  - file:\n      filename: my-file\n      source: my-source-file\n```\n\n| Field | Required | Description |\n| --- | :---: | --- |\n| `filename` | x | Name of destination file. This will be created within the package's data directory |\n| `source` | | Path to source file. This should be a relative path within the package manifest directory. This takes precedence over `content` if both are provided |\n| `content` | | Inline content for destination file |\n| `mode` | | Octal file mode for destination file |\n| `binary` | | Whether this file is an executable file for the package (expects bool, defaults to `false`) |\n\n##### `dependencies`\n\nDependencies for a package are specified in the following format. At minimum they contain a package name. They may optionally contain a list of required package\noptions and version range(s).\n\nExamples:\n\nPackage `foo` with at least version `1.0.2`\n\n```\nfoo \u003e= 1.0.2\n```\n\nPackage `foo` with at least version `1.0.2` but less than `2.0.0`\n\n```\nfoo \u003c 2.0.0, \u003e= 1.0.2\n```\n\nPackage `bar` with at least version `3.0.0`, option `optA` turned on, and option `optB` turned off\n\n```\nbar[optA,-optB] \u003e= 3.0.0\n```\n\n##### `tags`\n\nThe tags for a package should be a list of arbitrary string values corresponding to the supported platforms and architectures. They should be one or more of:\n\n* `docker`\n* `linux`\n* `darwin`\n* `amd64`\n* `arm`\n\n##### `options`\n\nThe options for a package allow defining optional feature flags. The value of these flags is available to templates in the package manifest.\n\nExample:\n\n```yaml\noptions:\n  - name: foo\n    description: Option foo\n    default: false\n```\n\nThis option could then be referenced as `.Package.Options.foo` in package templates.\n\n| Field | Required | Description |\n| --- | :---: | --- |\n| `name` | x | Name of the option |\n| `description` | | Description of the option |\n| `default` | | Default value for option (defaults to `false`) |\n\n##### `outputs`\n\nThe outputs defined in a package will be translated into environment variables for the user to consume.\n\nExample:\n\n```yaml\n  - name: socket_path\n    description: Path to the Cardano Node UNIX socket\n    value: '{{ .Paths.ContextDir }}/node-ipc/node.socket'\n```\n\nWhen used in package `cardano-node`, this will generate an env var named `CARDANO_NODE_SOCKET_PATH` with a path inside the package's data directory.\n\n| Field | Required | Description |\n| --- | :---: | --- |\n| `name` | x | Name of the output. This will have the package name automatically prepended and be made upper case |\n| `description` | | Description of the output |\n| `value` | x | Template that will be evaluated to generate the static output value |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fcardano-up","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblinklabs-io%2Fcardano-up","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblinklabs-io%2Fcardano-up/lists"}