GitHub Haskell Monthly Trending

jgm/pandoc

Universal markup converter

Pandoc

The universal markup converter

Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.

It can convert from

asciidoc (AsciiDoc markup)
bibtex (BibTeX bibliography)
biblatex (BibLaTeX bibliography)
bits (BITS XML, alias for jats)
commonmark (CommonMark Markdown)
commonmark_x (CommonMark Markdown with extensions)
creole (Creole 1.0)
csljson (CSL JSON bibliography)
csv (CSV table)
tsv (TSV table)
djot (Djot markup)
docbook (DocBook)
docx (Word docx)
dokuwiki (DokuWiki markup)
endnotexml (EndNote XML bibliography)
epub (EPUB)
fb2 (FictionBook2 e-book)
gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github; use markdown_github only if you need extensions not supported in gfm.
haddock (Haddock markup)
html (HTML)
ipynb (Jupyter notebook)
jats (JATS XML)
jira (Jira/Confluence wiki markup)
json (JSON version of native AST)
latex (LaTeX)
markdown (Pandoc’s Markdown)
markdown_mmd (MultiMarkdown)
markdown_phpextra (PHP Markdown Extra)
markdown_strict (original unextended Markdown)
mediawiki (MediaWiki markup)
man (roff man)
mdoc (mdoc manual page markup)
muse (Muse)
native (native Haskell)
odt (OpenDocument text document)
opml (OPML)
org (Emacs Org mode)
pod (Perl’s Plain Old Documentation)
pptx (PowerPoint)
ris (RIS bibliography)
rtf (Rich Text Format)
rst (reStructuredText)
t2t (txt2tags)
textile (Textile)
tikiwiki (TikiWiki markup)
twiki (TWiki markup)
typst (typst)
vimwiki (Vimwiki)
xlsx (Excel spreadsheet)
xml (XML version of native AST)
the path of a custom Lua reader, see Custom readers and writers below

It can convert to

ansi (text with ANSI escape codes, for terminal viewing)
asciidoc (modern AsciiDoc as interpreted by AsciiDoctor)
asciidoc_legacy (AsciiDoc as interpreted by asciidoc-py).
asciidoctor (deprecated synonym for asciidoc)
bbcode BBCode
bbcode_fluxbb BBCode (FluxBB)
bbcode_phpbb BBCode (phpBB)
bbcode_steam BBCode (Steam)
bbcode_hubzilla BBCode (Hubzilla)
bbcode_xenforo BBCode (xenForo)
beamer (LaTeX beamer slide show)
bibtex (BibTeX bibliography)
biblatex (BibLaTeX bibliography)
chunkedhtml (zip archive of multiple linked HTML files)
commonmark (CommonMark Markdown)
commonmark_x (CommonMark Markdown with extensions)
context (ConTeXt)
csljson (CSL JSON bibliography)
djot (Djot markup)
docbook or docbook4 (DocBook 4)
docbook5 (DocBook 5)
docx (Word docx)
dokuwiki (DokuWiki markup)
epub or epub3 (EPUB v3 book)
epub2 (EPUB v2)
fb2 (FictionBook2 e-book)
gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github; use markdown_github only if you need extensions not supported in gfm.
haddock (Haddock markup)
html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
html4 (XHTML 1.0 Transitional)
icml (InDesign ICML)
ipynb (Jupyter notebook)
jats_archiving (JATS XML, Archiving and Interchange Tag Set)
jats_articleauthoring (JATS XML, Article Authoring Tag Set)
jats_publishing (JATS XML, Journal Publishing Tag Set)
jats (alias for jats_archiving)
jira (Jira/Confluence wiki markup)
json (JSON version of native AST)
latex (LaTeX)
man (roff man)
markdown (Pandoc’s Markdown)
markdown_mmd (MultiMarkdown)
markdown_phpextra (PHP Markdown Extra)
markdown_strict (original unextended Markdown)
markua (Markua)
mediawiki (MediaWiki markup)
ms (roff ms)
muse (Muse)
native (native Haskell)
odt (OpenDocument text document)
opml (OPML)
opendocument (OpenDocument XML)
org (Emacs Org mode)
pdf (PDF)
plain (plain text)
pptx (PowerPoint slide show)
rst (reStructuredText)
rtf (Rich Text Format)
texinfo (GNU Texinfo)
textile (Textile)
slideous (Slideous HTML and JavaScript slide show)
slidy (Slidy HTML and JavaScript slide show)
dzslides (DZSlides HTML5 + JavaScript slide show)
revealjs (reveal.js HTML5 + JavaScript slide show)
s5 (S5 HTML and JavaScript slide show)
tei (TEI Simple)
typst (typst)
vimdoc (Vimdoc)
xml (XML version of native AST)
xwiki (XWiki markup)
zimwiki (ZimWiki markup)
the path of a custom Lua writer, see Custom readers and writers below

Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML.

Pandoc’s enhanced version of Markdown includes syntax for tables, definition lists, metadata blocks, footnotes, citations, math, and much more. See the User’s Manual below under Pandoc’s Markdown.

Pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the document (an abstract syntax tree or AST), and a set of writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer. Users can also run custom pandoc filters to modify the intermediate AST (see the documentation for filters and Lua filters).

Because pandoc’s intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other. Pandoc attempts to preserve the structural elements of a document, but not formatting details such as margin size. And some document elements, such as complex tables, may not fit into pandoc’s simple document model. While conversions from pandoc’s Markdown to all formats aspire to be perfect, conversions from formats more expressive than pandoc’s Markdown can be expected to be lossy.

Installing

Here’s how to install pandoc.

Documentation

Pandoc’s website contains a full User’s Guide. It is also available here as pandoc-flavored Markdown. The website also contains some examples of the use of pandoc, a limited online demo, and a WebAssembly-based online demo.

Contributing

Pull requests, bug reports, and feature requests are welcome. Please make sure to read the contributor guidelines before opening a new issue.

License

simplex-chat/simplex-chat

SimpleX - the first messaging network operating without user identifiers of any kind - 100% private by design! iOS, Android and desktop apps 📱!

| 30/03/2023 | EN, FR, CZ, PL |

SimpleX - the first messaging platform that has no user identifiers of any kind - 100% private by design!

Why we are building SimpleX Network

Welcome to SimpleX Chat!

📲 Install the app.
↔️ Connect to the team, join user groups and follow our updates.
🤝 Make a private connection with a friend.
🔤 Help translating SimpleX Chat.
⚡️ Contribute and support us with donations.

Learn more about SimpleX Chat.

Install the app

🖲 Protects your messages and metadata - who you talk to and when.
🔐 Double ratchet end-to-end encryption, with additional encryption layer.
📱 Mobile apps for Android (Google Play, APK) and iOS.
🚀 TestFlight preview for iOS with the new features 1-2 weeks earlier - limited to 10,000 users!
🖥 Available as a terminal (console) app / CLI on Linux, MacOS, Windows.

Connect to the team

You can connect to the team via the app using "chat with the developers button" available when you have no conversations in the profile, "Send questions and ideas" in the app settings or via our SimpleX address. Please connect to:

to ask any questions
to suggest any improvements
to share anything relevant

We are replying the questions manually, so it is not instant – it can take up to 24 hours.

If you are interested in helping us to integrate open-source language models, and in joining our team, please get in touch.

Join user groups

You can find the groups created by users in SimpleX Directory. It is also available as SimpleX bot that allows to add your own groups and communities to the directory. We are not responsible for the content shared in these groups.

Please note: The groups below are created for the users to be able to ask questions, make suggestions and ask questions about SimpleX Chat only.

You can join an English-speaking users group if you want to ask any questions: #SimpleX users group

There is also a group #simplex-devs for developers who build on SimpleX platform:

chat bots and automations
integrations with other apps
social apps and services
etc.

You can join these and other groups by opening these links in the app or by opening them in a desktop browser and scanning the QR code.

Follow our updates

We publish our updates and releases via:

Reddit, Twitter, Lemmy, Mastodon and Nostr.
SimpleX Chat team profile.
blog and RSS feed.
mailing list, very rarely.

Make a private connection

You need to share a link with your friend or scan a QR code from their phone, in person or during a video call, to make a connection and start messaging.

The channel through which you share the link does not have to be secure - it is enough that you can confirm who sent you the message and that your SimpleX connection is established.

After you connect, you can verify connection security code.

User guide (NEW)

Read about the app features and settings in the new User guide.

Contribute

We would love to have you join the development! You can help us with:

develop a chat bot for SimpleX Chat!
writing a tutorial or recipes about hosting servers, chat bots, etc.
developing features - please connect to us via chat so we can help you get started.

Help translating SimpleX Chat

Thanks to our users and Weblate, SimpleX Chat apps, website and documents are translated to many other languages.

Join our translators to help SimpleX grow!

locale	language	contributor	Android and iOS	website	Github docs
🇬🇧 en	English		✓	✓	✓
ar	العربية	jermanuts	-
🇧🇬 bg	Български
🇨🇿 cs	Čeština	zen0bit			✓
🇩🇪 de	Deutsch	mlanp
🇪🇸 es	Español	Mateyhv
🇫🇮 fi	Suomi
🇫🇷 fr	Français	ishi_sama			✓
🇮🇱 he	עִברִית		-
🇭🇺 hu	Magyar		-
🇮🇹 it	Italiano	unbranched
🇯🇵 ja	日本語
🇳🇱 nl	Nederlands	mika-nl
🇵🇱 pl	Polski	BxOxSxS
🇧🇷 pt-BR	Português		-
🇷🇺 ru	Русский
🇹🇭 th	ภาษาไทย	titapa-punpun
🇹🇷 tr	Türkçe
🇺🇦 uk	Українська
🇨🇳 zh-CHS	简体中文	sith-on-mars Float-hu

Languages in progress: Arabic, Japanese, Korean, Portuguese and others. We will be adding more languages as some of the already added are completed – please suggest new languages, review the translation guide and get in touch with us!

Please support us with your donations

Huge thank you to everybody who donated to SimpleX Chat!

We are prioritizing users privacy and security - it would be impossible without your support.

Our pledge to our users is that SimpleX protocols are and will remain open, and in public domain, - so anybody can build the future implementations of the clients and the servers. We are building SimpleX platform based on the same principles as email and web, but much more private and secure.

Your donations help us raise more funds - any amount, even the price of the cup of coffee, would make a big difference for us.

It is possible to donate via:

GitHub (commission-free) or OpenCollective (~10% commission).
BTC: bc1q2gy6f02nn6vvcxs0pnu29tpnpyz0qf66505d4u
XMR: 8A3ZWAXrrQddvnT1fPrtbK86ZAoM4nai3Gjg1LEow3JWcryJtovMnHYZnxTJpCLmAbfWbnPMeTzPmMBjAhyd4xoM89hYq1c
BCH: bitcoincash:qq6c8vfvxqrk6rhdysgvkhqc24sggkfsx5nqvdlqcg
ETH/USDT (Ethereum, Arbitrum One): 0xD7047Fe3Eecb2f2FF78d839dD927Be27Bc12c86a (donate.simplexchat.eth)
ZEC: t1fwjQW5gpFhDqXNhxqDWyF9j9WeKvVS5Jg
ZEC shielded: u16rnvkflumf5uw9frngc2lymvmzgdr2mmc9unyu0l44unwfmdcpfm0axujd2w34ct3ye709azxsqge45705lpvvqu264ltzvfay55ygyq
DOGE: D99pV4n9TrPxBPCkQGx4w4SMSa6QjRBxPf
SOL: 7JCf5m3TiHmYKZVr6jCu1KeZVtb9Y1jRMQDU69p5ARnu
please ask if you want to donate any other coins.

Thank you,

Evgeny

SimpleX Chat founder

Why privacy matters

Everyone should care about privacy and security of their communications - innocuous conversations can put you in danger even if there is nothing to hide.

One of the most shocking stories is the experience of Mohamedou Ould Salahi that he wrote about in his memoir and that is shown in The Mauritanian movie. He was put into Guantanamo camp, without trial, and was tortured there for 15 years after a phone call to his relative in Afghanistan, under suspicion of being involved in 9/11 attacks, even though he lived in Germany for the 10 years prior to the attacks.

It is not enough to use an end-to-end encrypted messenger, we all should use the messengers that protect the privacy of our personal networks - who we are connected with.

SimpleX approach to privacy and security

Complete privacy of your identity, profile, contacts and metadata

Unlike any other existing messaging platform, SimpleX has no identifiers assigned to the users - not even random numbers. This protects the privacy of who are you communicating with, hiding it from SimpleX platform servers and from any observers. Read more.

The best protection against spam and abuse

As you have no identifier on SimpleX platform, you cannot be contacted unless you share a one-time invitation link or an optional temporary user address. Read more.

Complete ownership, control and security of your data

SimpleX stores all user data on client devices, the messages are only held temporarily on SimpleX relay servers until they are received. Read more.

Users own SimpleX network

You can use SimpleX with your own servers and still communicate with people using the servers that are pre-configured in the apps or any other SimpleX servers. Read more.

Frequently asked questions

How SimpleX can deliver messages without any user identifiers? See v2 release announcement explaining how SimpleX works.
Why should I not just use Signal? Signal is a centralized platform that uses phone numbers to identify its users and their contacts. It means that while the content of your messages on Signal is protected with robust end-to-end encryption, there is a large amount of meta-data visible to Signal - who you talk with and when.
How is it different from Matrix, Session, Ricochet, Cwtch, etc., that also don't require user identities? Although these platforms do not require a real identity, they do rely on anonymous user identities to deliver messages – it can be, for example, an identity key or a random number. Using a persistent user identity, even anonymous, creates a risk that user's connection graph becomes known to the observers and/or service providers, and it can lead to de-anonymizing some users. If the same user profile is used to connect to two different people via any messenger other than SimpleX, these two people can confirm if they are connected to the same person - they would use the same user identifier in the messages. With SimpleX there is no meta-data in common between your conversations with different contacts - the quality that no other messaging platform has.

News and updates

Recent and important updates:

Jul 29, 2025 SimpleX Chat v6.4.1: welcome your contacts, review members to protect groups, and more.

Jul 3, 2025 SimpleX network: new experience of connecting with people — available in SimpleX Chat v6.4-beta.4

Mar 8, 2025. SimpleX Chat v6.3: new user experience and safety in public groups

Jan 14, 2025. SimpleX network: large groups and privacy-preserving content moderation

Dec 10, 2024. SimpleX network: preset servers operated by Flux, business chats and more with v6.2 of the apps

Oct 14, 2024. SimpleX network: security review of protocols design by Trail of Bits, v6.1 released with better calls and user experience.

Aug 14, 2024. SimpleX network: the investment from Jack Dorsey and Asymmetric, v6.0 released with the new user experience and private message routing

Jun 4, 2024. SimpleX network: private message routing, v5.8 released with IP address protection and chat themes

Mar 14, 2024. SimpleX Chat v5.6 beta: adding quantum resistance to Signal double ratchet algorithm.

Nov 25, 2023. SimpleX Chat v5.4 released: link mobile and desktop apps via quantum resistant protocol, and much better groups.

Apr 22, 2023. SimpleX Chat: vision and funding, v5.0 released with videos and files up to 1gb.

Mar 1, 2023. SimpleX File Transfer Protocol – send large files efficiently, privately and securely, soon to be integrated into SimpleX Chat apps..

Nov 8, 2022. Security audit by Trail of Bits, the new website and v4.2 released.

All updates

⚡ Quick installation of a terminal app

curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash

Once the chat client is installed, simply run simplex-chat from your terminal.

Read more about installing and using the terminal app.

SimpleX Platform design

SimpleX is a client-server network with a unique network topology that uses redundant, disposable message relay nodes to asynchronously pass messages via unidirectional (simplex) message queues, providing recipient and sender anonymity.

Unlike P2P networks, all messages are passed through one or several server nodes, that do not even need to have persistence. In fact, the current SMP server implementation uses in-memory message storage, persisting only the queue records. SimpleX provides better metadata protection than P2P designs, as no global participant identifiers are used to deliver messages, and avoids the problems of P2P networks.

Unlike federated networks, the server nodes do not have records of the users, do not communicate with each other and do not store messages after they are delivered to the recipients. There is no way to discover the full list of servers participating in SimpleX network. This design avoids the problem of metadata visibility that all federated networks have and better protects from the network-wide attacks.

Only the client devices have information about users, their contacts and groups.

See SimpleX whitepaper for more information on platform objectives and technical design.

See SimpleX Chat Protocol for the format of messages sent between chat clients over SimpleX Messaging Protocol.

Privacy and security: technical details and limitations

SimpleX Chat is a work in progress – we are releasing improvements as they are ready. You have to decide if the current state is good enough for your usage scenario.

We compiled a glossary of terms used to describe communication systems to help understand some terms below and to help compare advantages and disadvantages of various communication systems.

What is already implemented:

Instead of user profile identifiers used by all other platforms, even the most private ones, SimpleX uses pairwise per-queue identifiers (2 addresses for each unidirectional message queue, with an optional 3rd address for push notifications on iOS, 2 queues in each connection between the users). It makes observing the network graph on the application level more difficult, as for n users there can be up to n * (n-1) message queues.
End-to-end encryption in each message queue using NaCl cryptobox. This is added to allow redundancy in the future (passing each message via several servers), to avoid having the same ciphertext in different queues (that would only be visible to the attacker if TLS is compromised). The encryption keys used for this encryption are not rotated, instead we are planning to rotate the queues. Curve25519 keys are used for key negotiation.
Double ratchet end-to-end encryption in each conversation between two users (or group members). This is the same algorithm that is used in Signal and many other messaging apps; it provides OTR messaging with forward secrecy (each message is encrypted by its own ephemeral key) and break-in recovery (the keys are frequently re-negotiated as part of the message exchange). Two pairs of Curve448 keys are used for the initial key agreement, initiating party passes these keys via the connection link, accepting side - in the header of the confirmation message.
Post-quantum resistant key exchange in double ratchet protocol on every ratchet step. Read more in this post and also see this publication by Apple explaining the need for post-quantum key rotation.
Additional layer of encryption using NaCL cryptobox for the messages delivered from the server to the recipient. This layer avoids having any ciphertext in common between sent and received traffic of the server inside TLS (and there are no identifiers in common as well).
Several levels of content padding to frustrate message size attacks.
All message metadata, including the time when the message was received by the server (rounded to a second) is sent to the recipients inside an encrypted envelope, so even if TLS is compromised it cannot be observed.
Only TLS 1.2/1.3 are allowed for client-server connections, limited to cryptographic algorithms: CHACHA20POLY1305_SHA256, Ed25519/Ed448, Curve25519/Curve448.
To protect against replay attacks SimpleX servers require tlsunique channel binding as session ID in each client command signed with per-queue ephemeral key.
To protect your IP address from unknown messaging relays, and for per-message transport anonymity (compared with Tor/VPN per-connection anonymity), from v6.0 all SimpleX Chat clients use private message routing by default. Read more in this post.
To protect your IP address from unknown file relays, when SOCKS proxy is not enabled SimpleX Chat clients ask for a confirmation before downloading the files from unknown servers.
To protect your IP address from known servers all SimpleX Chat clients support accessing messaging servers via Tor - see v3.1 release announcement for more details.
Local database encryption with passphrase - your contacts, groups and all sent and received messages are stored encrypted. If you used SimpleX Chat before v4.0 you need to enable the encryption via the app settings.
Transport isolation - different TCP connections and Tor circuits are used for traffic of different user profiles, optionally - for different contacts and group member connections.
Manual messaging queue rotations to move conversation to another SMP relay.
Sending end-to-end encrypted files using XFTP protocol.
Local files encryption.
Reproducible server builds.

We plan to add:

Automatic message queue rotation and redundancy. Currently the queues created between two users are used until the queue is manually changed by the user or contact is deleted. We are planning to add automatic queue rotation to make these identifiers temporary and rotate based on some schedule TBC (e.g., every X messages, or every X hours/days).
Message "mixing" - adding latency to message delivery, to protect against traffic correlation by message time.
Reproducible clients builds – this is a complex problem, but we are aiming to have it in 2025 at least partially.
Recipients' XFTP relays to reduce traffic and conceal IP addresses from the relays chosen, and potentially controlled, by another party.

For developers

You can:

create chat bots and services.
run simplex-chat terminal CLI to execute individual chat commands, e.g. to send messages as part of shell script execution.
use SimpleX Chat library to integrate chat functionality into your mobile apps.
create chat bots and services in Haskell - see simple and more advanced chat bot example.

If you are considering developing with SimpleX platform please get in touch for any advice and support.

Please also join #simplex-devs group to ask any questions and share your success stories.

Develop a chat bot

You can create a chat bot or any chat-based service in any language running SimpleX Chat terminal CLI as a local WebSocket server.

See our new bot API reference. Most of it is automatically generated from core library types, so it stays up to date.

Also see TypeScript SimpleX Chat client and JavaScript chat bot example.

Roadmap

✅ Easy to deploy SimpleX server with in-memory message storage, without any dependencies.
✅ Terminal (console) client with groups and files support.
✅ One-click SimpleX server deployment on Linode.
✅ End-to-end encryption using double-ratchet protocol with additional encryption layer.
✅ Mobile apps v1 for Android and iOS.
✅ Private instant notifications for Android using background service.
✅ Haskell chat bot templates.
✅ v2.0 - supporting images and files in mobile apps.
✅ Manual chat history deletion.
✅ End-to-end encrypted WebRTC audio and video calls via the mobile apps.
✅ Privacy preserving instant notifications for iOS using Apple Push Notification service.
✅ Chat database export and import.
✅ Chat groups in mobile apps.
✅ Connecting to messaging servers via Tor.
✅ Dual server addresses to access messaging servers as v3 hidden services.
✅ Chat server and TypeScript client SDK to develop chat interfaces, integrations and chat bots (ready for announcement).
✅ Incognito mode to share a new random name with each contact.
✅ Chat database encryption.
✅ Automatic chat history deletion.
✅ Links to join groups and improve groups stability.
✅ Voice messages (with recipient opt-out per contact).
✅ Basic authentication for SMP servers (to authorize creating new queues).
✅ View deleted messages, full message deletion by sender (with recipient opt-in per contact).
✅ Block screenshots and view in recent apps.
✅ Advanced server configuration.
✅ Disappearing messages (with recipient opt-in per-contact).
✅ "Live" messages.
✅ Contact verification via a separate out-of-band channel.
✅ Multiple user profiles in the same chat database.
✅ Optionally avoid re-using the same TCP session for multiple connections.
✅ Preserve message drafts.
✅ File server to optimize for efficient and private sending of large files.
✅ Improved audio & video calls.
✅ Support older Android OS and 32-bit CPUs.
✅ Hidden chat profiles.
✅ Sending and receiving large files via XFTP protocol.
✅ Video messages.
✅ App access passcode.
✅ Improved Android app UI design.
✅ Optional alternative access password.
✅ Message reactions
✅ Message editing history
✅ Reduced battery and traffic usage in large groups.
✅ Message delivery confirmation (with sender opt-out per contact).
✅ Desktop client.
✅ Encryption of local files stored in the app.
✅ Using mobile profiles from the desktop app.
✅ Private notes.
✅ Improve sending videos (including encryption of locally stored videos).
✅ Post-quantum resistant key exchange in double ratchet protocol.
✅ Message delivery relay for senders (to conceal IP address from the recipients' servers and to reduce the traffic).
✅ Support multiple network operators in the app.
🏗 Large groups, communities and public channels.
🏗 Short links to connect and join groups.
🏗 Improve stability and reduce battery usage.
🏗 Improve experience for the new users.
Privacy & security slider - a simple way to set all settings at once.
SMP queue redundancy and rotation (manual is supported).
Include optional message into connection request sent via contact address.
Improved navigation and search in the conversation (expand and scroll to quoted message, scroll to search results, etc.).
Feeds/broadcasts.
Ephemeral/disappearing/OTR conversations with the existing contacts.
Privately share your location.
Web widgets for custom interactivity in the chats.
Programmable chat automations / rules (automatic replies/forward/deletion/sending, reminders, etc.).
Privacy-preserving identity server for optional DNS-based contact/group addresses to simplify connection and discovery, but not used to deliver messages:
- keep all your contacts and groups even if you lose the domain.
- the server doesn't have information about your contacts and groups.
High capacity multi-node SMP relays.

Disclaimers

SimpleX protocols and security model was reviewed, and had many breaking changes and improvements in v1.0.0.

The implementation security assessment of SimpleX cryptography and networking was done in October 2022 by Trail of Bits – see the announcement.

The cryptographic review of SimpleX protocols was done in July 2024 by Trail of Bits – see the announcement.

SimpleX Chat is still a relatively early stage platform (the mobile apps were released in March 2022), so you may discover some bugs and missing features. We would really appreciate if you let us know anything that needs to be fixed or improved.

The default servers configured in the app are provided on the best effort basis. We are currently not guaranteeing any SLAs, although historically our servers had over 99.9% uptime each.

We have never provided or have been requested access to our servers or any information from our servers by any third parties. If we are ever requested to provide such access or information, we will be following due legal process.

We do not log IP addresses of the users and we do not perform any traffic correlation on our servers. If transport level security is critical you must use Tor or some other similar network to access messaging servers. We will be improving the client applications to reduce the opportunities for traffic correlation.

Please read more in Privacy Policy.

Security contact

Please see our Security Policy on how to report security vulnerabilities to us. We will coordinate the fix and disclosure.

Please do NOT report security vulnerabilities via GitHub issues.

License

This software is licensed under the GNU Affero General Public License version 3 (AGPLv3). See the LICENSE file for details. The SimpleX and SimpleX Chat name, logo, associated branding materials, and application and website graphic assets (illustrations, images, visual designs, etc.) are not covered by this license and are subject to the terms outlined in the TRADEMARK and ASSETS_LICENSE files respectively.

If you want to use any graphic assets in your publications, please ask for permission. Texts can be used as direct quotes, referencing the source.

hadolint/hadolint

Dockerfile linter, validate inline bash, written in Haskell

Hadolint - Haskell Dockerfile Linter

A smarter Dockerfile linter that helps you build best practice Docker images. The linter parses the Dockerfile into an AST and performs rules on top of the AST. It stands on the shoulders of ShellCheck to lint the Bash code inside RUN instructions.

🌐 Check the online version on hadolint.github.io/hadolint

How to use

You can run hadolint locally to lint your Dockerfile.

hadolint <Dockerfile>
hadolint --ignore DL3003 --ignore DL3006 <Dockerfile> # exclude specific rules
hadolint --trusted-registry my-company.com:500 <Dockerfile> # Warn when using untrusted FROM images

Docker comes to the rescue, providing an easy way how to run hadolint on most platforms. Just pipe your Dockerfile to docker run:

docker run --rm -i hadolint/hadolint < Dockerfile
# OR
docker run --rm -i ghcr.io/hadolint/hadolint < Dockerfile

or using Podman:

podman run --rm -i docker.io/hadolint/hadolint < Dockerfile
# OR
podman run --rm -i ghcr.io/hadolint/hadolint < Dockerfile

or using Windows PowerShell:

cat .\Dockerfile | docker run --rm -i hadolint/hadolint

Install

You can download prebuilt binaries for OSX, Windows and Linux from the latest release page. However, if this does not work for you, please fall back to container (Docker), brew or source installation.

On OSX, you can use brew to install hadolint.

brew install hadolint

On Windows, you can use scoop to install hadolint.

scoop install hadolint

On distributions that have nix installed, you can use the hadolint package to run ad-hoc shells or permanently install hadolint into your environment.

As mentioned earlier, hadolint is available as a container image:

docker pull hadolint/hadolint
# OR
docker pull ghcr.io/hadolint/hadolint

If you need a container with shell access, use the Debian or Alpine variants:

docker pull hadolint/hadolint:latest-debian
# OR
docker pull hadolint/hadolint:latest-alpine
# OR
docker pull ghcr.io/hadolint/hadolint:latest-debian
# OR
docker pull ghcr.io/hadolint/hadolint:latest-alpine

You can also build hadolint locally. You need Haskell and the cabal build tool to build the binary.

git clone https://github.com/hadolint/hadolint \
  && cd hadolint \
  && cabal configure \
  && cabal build \
  && cabal install

If you want the VS Code Hadolint extension to use Hadolint in a container, you can use the following wrapper script:

#!/bin/bash
dockerfile="$1"
shift
docker run --rm -i hadolint/hadolint hadolint "$@" - < "$dockerfile"

CLI

hadolint --help

hadolint - Dockerfile Linter written in Haskell

Usage: hadolint [-v|--version] [-c|--config FILENAME] [DOCKERFILE...]
                [--file-path-in-report FILEPATHINREPORT] [--no-fail]
                [--no-color] [-V|--verbose] [-f|--format ARG] [--error RULECODE]
                [--warning RULECODE] [--info RULECODE] [--style RULECODE]
                [--ignore RULECODE]
                [--trusted-registry REGISTRY (e.g. docker.io)]
                [--require-label LABELSCHEMA (e.g. maintainer:text)]
                [--strict-labels] [--disable-ignore-pragma]
                [-t|--failure-threshold THRESHOLD]
  Lint Dockerfile for errors and best practices

Available options:
  -h,--help                Show this help text
  -v,--version             Show version
  -c,--config FILENAME     Path to the configuration file
  --file-path-in-report FILEPATHINREPORT
                           The file path referenced in the generated report.
                           This only applies for the 'checkstyle', 'codeclimate',
                           'sonarqube' and 'gitlab_codeclimate' formats and is
                           useful when running Hadolint with Docker to set the
                           correct file path.
  --no-fail                Don't exit with a failure status code when any rule
                           is violated
  --no-color               Don't colorize output
  -V,--verbose             Enables verbose logging of hadolint's output to
                           stderr
  -f,--format ARG          The output format for the results [tty | json |
                           checkstyle | codeclimate | gitlab_codeclimate | gnu |
                           codacy | sonarqube | sarif] (default: tty)
  --error RULECODE         Make the rule `RULECODE` have the level `error`
  --warning RULECODE       Make the rule `RULECODE` have the level `warning`
  --info RULECODE          Make the rule `RULECODE` have the level `info`
  --style RULECODE         Make the rule `RULECODE` have the level `style`
  --ignore RULECODE        A rule to ignore. If present, the ignore list in the
                           config file is ignored
  --trusted-registry REGISTRY (e.g. docker.io)
                           A docker registry to allow to appear in FROM
                           instructions
  --require-label LABELSCHEMA (e.g. maintainer:text)
                           The option --require-label=label:format makes
                           Hadolint check that the label `label` conforms to
                           format requirement `format`
  --strict-labels          Do not permit labels other than specified in
                           `label-schema`
  --disable-ignore-pragma  Disable inline ignore pragmas `# hadolint
                           ignore=DLxxxx`
  -t,--failure-threshold THRESHOLD
                           Exit with failure code only when rules with a
                           severity equal to or above THRESHOLD are violated.
                           Accepted values: [error | warning | info | style |
                           ignore | none] (default: info)

Configure

Configuration files can be used globally or per project. Hadolint looks for configuration files in the following locations or their platform specific equivalents in this order and uses the first one exclusively:

$PWD/.hadolint.yaml
$XDG_CONFIG_HOME/hadolint.yaml
$HOME/.config/hadolint.yaml
$HOME/.hadolint/hadolint.yaml or $HOME/hadolint/config.yaml
$HOME/.hadolint.yaml

In windows, the %LOCALAPPDATA% environment variable is used instead of XDG_CONFIG_HOME. Config files can have either yaml or yml extensions.

hadolint full yaml config file schema

failure-threshold: string               # name of threshold level (error | warning | info | style | ignore | none)
format: string                          # Output format (tty | json | checkstyle | codeclimate | gitlab_codeclimate | gnu | codacy)
ignored: [string]                       # list of rules
label-schema:                           # See Linting Labels below for specific label-schema details
  author: string                        # Your name
  contact: string                       # email address
  created: timestamp                    # rfc3339 datetime
  version: string                       # semver
  documentation: string                 # url
  git-revision: string                  # hash
  license: string                       # spdx
no-color: boolean                       # true | false
no-fail: boolean                        # true | false
override:
  error: [string]                       # list of rules
  warning: [string]                     # list of rules
  info: [string]                        # list of rules
  style: [string]                       # list of rules
strict-labels: boolean                  # true | false
disable-ignore-pragma: boolean          # true | false
trustedRegistries: string | [string]    # registry or list of registries

hadolint supports specifying the ignored rules using a configuration file. The configuration file should be in yaml format. This is one valid configuration file as an example:

ignored:
  - DL3000
  - SC1010

Additionally, hadolint can warn you when images from untrusted repositories are being used in Dockerfiles, you can append the trustedRegistries keys to the configuration file, as shown below:

ignored:
  - DL3000
  - SC1010

trustedRegistries:
  - docker.io
  - my-company.com:5000
  - "*.gcr.io"

If you want to override the severity of specific rules, you can do that too:

override:
  error:
    - DL3001
    - DL3002
  warning:
    - DL3042
    - DL3033
  info:
    - DL3032
  style:
    - DL3015

failure-threshold Exit with failure code only when rules with a severity above THRESHOLD are violated (Available in v2.6.0+)

failure-threshold: info
override:
  warning:
    - DL3042
    - DL3033
  info:
    - DL3032

Additionally, you can pass a custom configuration file in the command line with the --config option

hadolint --config /path/to/config.yaml Dockerfile

To pass a custom configuration file (using relative or absolute path) to a container, use the following command:

docker run --rm -i -v /your/path/to/hadolint.yaml:/.config/hadolint.yaml hadolint/hadolint < Dockerfile
# OR
docker run --rm -i -v /your/path/to/hadolint.yaml:/.config/hadolint.yaml ghcr.io/hadolint/hadolint < Dockerfile

In addition to config files, Hadolint can be configured with environment variables.

NO_COLOR=1                               # Set or unset. See https://no-color.org
HADOLINT_NOFAIL=1                        # Truthy value e.g. 1, true or yes
HADOLINT_VERBOSE=1                       # Truthy value e.g. 1, true or yes
HADOLINT_FORMAT=json                     # Output format (tty | json | checkstyle | codeclimate | gitlab_codeclimate | gnu | codacy | sarif )
HADOLINT_FAILURE_THRESHOLD=info          # threshold level (error | warning | info | style | ignore | none)
HADOLINT_OVERRIDE_ERROR=DL3010,DL3020    # comma separated list of rule codes
HADOLINT_OVERRIDE_WARNING=DL3010,DL3020  # comma separated list of rule codes
HADOLINT_OVERRIDE_INFO=DL3010,DL3020     # comma separated list of rule codes
HADOLINT_OVERRIDE_STYLE=DL3010,DL3020    # comma separated list of rule codes
HADOLINT_IGNORE=DL3010,DL3020            # comma separated list of rule codes
HADOLINT_STRICT_LABELS=1                 # Truthy value e.g. 1, true or yes
HADOLINT_DISABLE_IGNORE_PRAGMA=1         # Truthy value e.g. 1, true or yes
HADOLINT_TRUSTED_REGISTRIES=docker.io    # comma separated list of registry urls
HADOLINT_REQUIRE_LABELS=maintainer:text  # comma separated list of label schema items

Non-Posix Shells

When using base images with non-posix shells as default (e.g. Windows based images) a special pragma hadolint shell can specify which shell the base image uses, so that Hadolint can automatically ignore all shell-specific rules.

FROM mcr.microsoft.com/windows/servercore:ltsc2022
# hadolint shell=powershell
RUN Get-Process notepad | Stop-Process

Ignoring Rules

Inline ignores

It is also possible to ignore rules by adding a special comment directly above the Dockerfile statement for which you want to make an exception for. Such comments look like # hadolint ignore=DL3001,SC1081. For example:

# hadolint ignore=DL3006
FROM ubuntu

# hadolint ignore=DL3003,SC1035 # We accept these issues, because ...
RUN cd /tmp && echo "hello!"

The comment "inline ignores" applies only to the statement following it.

Comments are allowed after the ignore=..., you need an extra #

Global ignores

Rules can also be ignored on a per-file basis using the global ignore pragma. It works just like inline ignores, except that it applies to the whole file instead of just the next line.

# hadolint global ignore=DL3003,DL3006,SC1035 # We accept these issues, because ...
FROM ubuntu

RUN cd /tmp && echo "foo"

Linting Labels

Hadolint is able to check if specific labels are present and conform to a predefined label schema. First, a label schema must be defined either via the command line:

hadolint --require-label author:text --require-label version:semver Dockerfile

or via the config file:

label-schema:
  author: text
  contact: email
  created: rfc3339
  version: semver
  documentation: url
  git-revision: hash
  license: spdx

The value of a label can be either of text, url, semver, hash or rfc3339:

Schema	Description
text	Anything
rfc3339	A time, formatted according to RFC 3339
semver	A semantic version
url	A URI as described in RFC 3986
hash	Either a short or a long Git hash
spdx	An SPDX license identifier
email	An email address conforming to RFC 5322

By default, Hadolint ignores any label that is not specified in the label schema. To warn against such additional labels, turn on strict labels, using the command line:

hadolint --strict-labels --require-label version:semver Dockerfile

or the config file:

strict-labels: true

When strict labels is enabled, but no label schema is specified, hadolint will warn if any label is present.

Note on dealing with variables in labels

It is a common pattern to fill the value of a label not statically, but rather dynamically at build time by using a variable:

FROM debian:buster
ARG VERSION="du-jour"
LABEL version="${VERSION}"

To allow this, the label schema must specify text as value for that label:

label-schema:
  version: text

Integrations

To get most of hadolint, it is useful to integrate it as a check in your CI or into your editor, or as a pre-commit hook, to lint your Dockerfile as you write it. See our Integration docs.

Rules

An incomplete list of implemented rules. Click on the error code to get more detailed information.

Rules with the prefix DL are from hadolint. Have a look at Rules.hs to find the implementation of the rules.
Rules with the SC prefix are from ShellCheck (only the most common rules are listed, there are dozens more).

Please create an issue if you have an idea for a good rule.

Rule	Default Severity	Description
DL1001	Ignore	Please refrain from using inline ignore pragmas `# hadolint ignore=DLxxxx`.
DL3000	Error	Use absolute WORKDIR.
DL3001	Info	For some bash commands it makes no sense running them in a Docker container like ssh, vim, shutdown, service, ps, free, top, kill, mount, ifconfig.
DL3002	Warning	Last user should not be root.
DL3003	Warning	Use WORKDIR to switch to a directory.
DL3004	Error	Do not use sudo as it leads to unpredictable behavior. Use a tool like gosu to enforce root.
DL3006	Warning	Always tag the version of an image explicitly.
DL3007	Warning	Using latest is prone to errors if the image will ever update. Pin the version explicitly to a release tag.
DL3008	Warning	Pin versions in `apt-get install`.
DL3009	Info	Delete the apt-get lists after installing something.
DL3010	Info	Use ADD for extracting archives into an image.
DL3011	Error	Valid UNIX ports range from 0 to 65535.
DL3012	Error	Multiple `HEALTHCHECK` instructions.
DL3013	Warning	Pin versions in pip.
DL3014	Warning	Use the `-y` switch.
DL3015	Info	Avoid additional packages by specifying `--no-install-recommends`.
DL3016	Warning	Pin versions in `npm`.
DL3018	Warning	Pin versions in `apk add`. Instead of `apk add <package>` use `apk add <package>=<version>`.
DL3019	Info	Use the `--no-cache` switch to avoid the need to use `--update` and remove `/var/cache/apk/*` when done installing packages.
DL3020	Error	Use `COPY` instead of `ADD` for files and folders.
DL3021	Error	`COPY` with more than 2 arguments requires the last argument to end with `/`
DL3022	Warning	`COPY --from` should reference a previously defined `FROM` alias
DL3023	Error	`COPY --from` cannot reference its own `FROM` alias
DL3024	Error	`FROM` aliases (stage names) must be unique
DL3025	Warning	Use arguments JSON notation for CMD and ENTRYPOINT arguments
DL3026	Error	Use only an allowed registry in the `FROM image`
DL3027	Warning	Do not use `apt` as it is meant to be an end-user tool, use `apt-get` or `apt-cache` instead
DL3028	Warning	Pin versions in gem install. Instead of `gem install <gem>` use `gem install <gem>:<version>`
DL3029	Warning	Do not use --platform flag with FROM.
DL3030	Warning	Use the `-y` switch to avoid manual input `yum install -y <package>`
DL3032	Warning	`yum clean all` missing after yum command.
DL3033	Warning	Specify version with `yum install -y <package>-<version>`
DL3034	Warning	Non-interactive switch missing from `zypper` command: `zypper install -y`
DL3035	Warning	Do not use `zypper dist-upgrade`.
DL3036	Warning	`zypper clean` missing after zypper use.
DL3037	Warning	Specify version with `zypper install -y <package>[=]<version>`.
DL3038	Warning	Use the `-y` switch to avoid manual input `dnf install -y <package>`
DL3040	Warning	`dnf clean all` missing after dnf command.
DL3041	Warning	Specify version with `dnf install -y <package>-<version>`
DL3042	Warning	Avoid cache directory with `pip install --no-cache-dir <package>`.
DL3043	Error	`ONBUILD`, `FROM` or `MAINTAINER` triggered from within `ONBUILD` instruction.
DL3044	Error	Do not refer to an environment variable within the same `ENV` statement where it is defined.
DL3045	Warning	`COPY` to a relative destination without `WORKDIR` set.
DL3046	Warning	`useradd` without flag `-l` and high UID will result in excessively large Image.
DL3047	Info	`wget` without flag `--progress` will result in excessively bloated build logs when downloading larger files.
DL3048	Style	Invalid Label Key
DL3049	Info	Label `<label>` is missing.
DL3050	Info	Superfluous label(s) present.
DL3051	Warning	Label `<label>` is empty.
DL3052	Warning	Label `<label>` is not a valid URL.
DL3053	Warning	Label `<label>` is not a valid time format - must conform to RFC3339.
DL3054	Warning	Label `<label>` is not a valid SPDX license identifier.
DL3055	Warning	Label `<label>` is not a valid git hash.
DL3056	Warning	Label `<label>` does not conform to semantic versioning.
DL3057	Ignore	`HEALTHCHECK` instruction missing.
DL3058	Warning	Label `<label>` is not a valid email format - must conform to RFC5322.
DL3059	Info	Multiple consecutive `RUN` instructions. Consider consolidation.
DL3060	Info	`yarn cache clean` missing after `yarn install` was run.
DL3061	Error	Invalid instruction order. Dockerfile must begin with `FROM`, `ARG` or comment.
DL3062	Warning	Pin versions in go install. Instead of `go install <package>` use `go install <package>@<version>`
DL3063	Warning	Stage name should not be a reserved word
DL4000	Error	`MAINTAINER` is deprecated.
DL4001	Warning	Either use Wget or Curl but not both.
DL4003	Warning	Multiple `CMD` instructions found.
DL4004	Error	Multiple `ENTRYPOINT` instructions found.
DL4005	Warning	Use `SHELL` to change the default shell.
DL4006	Warning	Set the `SHELL` option -o pipefail before `RUN` with a pipe in it
SC1000		`$` is not used specially and should therefore be escaped.
SC1001		This `\c` will be a regular `'c'` in this context.
SC1007		Remove space after `=` if trying to assign a value (or for empty string, use `var='' ...`).
SC1010		Use semicolon or linefeed before `done` (or quote to make it literal).
SC1018		This is a unicode non-breaking space. Delete it and retype as space.
SC1035		You need a space here
SC1045		It's not `foo &; bar`, just `foo & bar`.
SC1065		Trying to declare parameters? Don't. Use `()` and refer to params as `$1`, `$2` etc.
SC1066		Don't use $ on the left side of assignments.
SC1068		Don't put spaces around the `=` in assignments.
SC1077		For command expansion, the tick should slant left (` vs ´).
SC1078		Did you forget to close this double-quoted string?
SC1079		This is actually an end quote, but due to next char, it looks suspect.
SC1081		Scripts are case sensitive. Use `if`, not `If`.
SC1083		This `{/}` is literal. Check expression (missing `;/\n`?) or quote it.
SC1086		Don't use `$` on the iterator name in for loops.
SC1087		Braces are required when expanding arrays, as in `${array[idx]}`.
SC1091		Not following: Reasons include: file not found, no permissions, not included on the command line, not allowing shellcheck to follow files with -x, etc.
SC1095		You need a space or linefeed between the function name and body.
SC1097		Unexpected `==`. For assignment, use `=`. For comparison, use `[ .. ]` or `[[ .. ]]`.
SC1098		Quote/escape special characters when using `eval`, e.g. `eval "a=(b)"`.
SC1099		You need a space before the `#`.
SC2002		Useless cat. Consider `cmd < file \| ..` or `cmd file \| ..` instead.
SC2015		Note that `A && B \|\| C` is not if-then-else. C may run when A is true.
SC2026		This word is outside of quotes. Did you intend to 'nest '"'single quotes'"' instead'?
SC2028		`echo` won't expand escape sequences. Consider `printf`.
SC2035		Use `./glob` or `-- glob` so names with dashes won't become options.
SC2039		In POSIX sh, something is undefined.
SC2046		Quote this to prevent word splitting
SC2086		Double quote to prevent globbing and word splitting.
SC2140		Word is in the form `"A"B"C"` (B indicated). Did you mean `"ABC"` or `"A\"B\"C"`?
SC2154		var is referenced but not assigned.
SC2155		Declare and assign separately to avoid masking return values.
SC2164		Use `cd ... \|\| exit` in case `cd` fails.

Develop

If you are an experienced Haskeller, we would be very grateful if you would tear our code apart in a review.

To compile, you will need a recent Haskell environment and cabal-install.

Setup

Clone repository

git clone --recursive git@github.com:hadolint/hadolint.git

Install dependencies and compile source

cabal configure
cabal update
cabal build

(Optional) Install Hadolint on your system
```
cabal install
```

REPL

The easiest way to try out the parser is using the REPL.

# start the repl
cabal repl
# overload strings to be able to use Text
:set -XOverloadedStrings
# import parser library
import Language.Docker
# parse instruction and look at AST representation
parseText "FROM debian:jessie"

Tests

Compile with unit tests and run them:

cabal configure --enable-tests
cabal build --enable-tests
cabal test

Run integration tests:

./integration_test.sh

AST

Dockerfile syntax is fully described in the Dockerfile reference. Just take a look at Syntax.hs in the language-docker project to see the AST definition.

Building against custom libraries

Hadolint uses many libraries to do the dirty work. In particular, language-docker is used to parse Dockerfiles and produce an AST which then can be analyzed. To build Hadolint against a custom version of such libraries, do the following. This example uses language-docker, but it would work with any other library as well.

In the same directory (e.g. /home/user/repos) clone Hadolint and language-docker git repositories

cd /home/user/repos
git clone https://github.com/hadolint/hadolint.git
git clone https://github.com/hadolint/language-docker.git

Make your modifications to language-docker
In the Hadolint repo, edit the cabal.project file, such that the packages property points to the other repo too

[...]
packages:
  .
  ../language-docker
[...]

Recompile Hadolint and run the tests

cd /home/user/repos/hadolint
cabal configure --enable-tests
cabal build --enable-tests
cabal test

Alternatives

replicatedhq/dockerfilelint, the other linter used by the super-linter
RedCoolBeans/dockerlint
projectatomic/dockerfile_lint

PostgREST/postgrest

REST API for any Postgres database

PostgREST serves a fully RESTful API from any existing PostgreSQL database. It provides a cleaner, more standards-compliant, faster API than you are likely to write from scratch.

Usage

See the docs for how to install PostgREST on your platform. You can also use Docker.
Invoke for help:
```
postgrest --help
```

Documentation

Latest documentation is at postgrest.org. You can contribute to the docs in PostgREST/postgrest/docs.

Performance

TLDR; subsecond response times for up to 2000 requests/sec on Heroku free tier. If you're used to servers written in interpreted languages, prepare to be pleasantly surprised by PostgREST performance.

Three factors contribute to the speed. First the server is written in Haskell using the Warp HTTP server (aka a compiled language with lightweight threads). Next it delegates as much calculation as possible to the database including

Serializing JSON responses directly in SQL
Data validation
Authorization
Combined row counting and retrieval
Data post in single command (returning *)

Finally it uses the database efficiently with the Hasql library by

Keeping a pool of db connections
Using the PostgreSQL binary protocol
Being stateless to allow horizontal scaling

Security

PostgREST handles authentication (via JSON Web Tokens) and delegates authorization to the role information defined in the database. This ensures there is a single declarative source of truth for security. When dealing with the database the server assumes the identity of the currently authenticated user, and for the duration of the connection cannot do anything the user themselves couldn't. Other forms of authentication can be built on top of the JWT primitive. See the docs for more information.

Versioning

A robust long-lived API needs the freedom to exist in multiple versions. PostgREST does versioning through database schemas. This allows you to expose tables and views without making the app brittle. Underlying tables can be superseded and hidden behind public facing views.

Self-documentation

PostgREST uses the OpenAPI standard to generate up-to-date documentation for APIs. You can use a tool like Swagger-UI to render interactive documentation for demo requests against the live API server.

This project uses HTTP to communicate other metadata as well. For instance the number of rows returned by an endpoint is reported by - and limited with - range headers. More about that.

Data Integrity

Rather than relying on an Object Relational Mapper and custom imperative coding, this system requires you to put declarative constraints directly into your database. Hence no application can corrupt your data (including your API server).

The PostgREST exposes HTTP interface with safeguards to prevent surprises, such as enforcing idempotent PUT requests.

See examples of PostgreSQL constraints and the API guide.

Supporting development

You can help PostgREST ongoing maintenance and development by making a regular donation through Patreon https://www.patreon.com/postgrest

Every donation will be spent on making PostgREST better for the whole community.

Contributing

Contributions are always welcome and appreciated. Please see the Contributing guidelines.

Thanks

The PostgREST organization is grateful to:

The project sponsors and backers who support PostgREST's development.
The project contributors who have improved PostgREST immensely with their code and good judgement. See more details in the changelog.

The cool logo came from Mikey Casalaina.

koalaman/shellcheck

ShellCheck, a static analysis tool for shell scripts

ShellCheck - A shell script static analysis tool

ShellCheck is a GPLv3 tool that gives warnings and suggestions for bash/sh shell scripts:

The goals of ShellCheck are

To point out and clarify typical beginner's syntax issues that cause a shell to give cryptic error messages.
To point out and clarify typical intermediate level semantic problems that cause a shell to behave strangely and counter-intuitively.
To point out subtle caveats, corner cases and pitfalls that may cause an advanced user's otherwise working script to fail under future circumstances.

See the gallery of bad code for examples of what ShellCheck can help you identify!

How to use

There are a number of ways to use ShellCheck!

On the web

Paste a shell script on https://www.shellcheck.net for instant feedback.

ShellCheck.net is always synchronized to the latest git commit, and is the easiest way to give ShellCheck a go. Tell your friends!

From your terminal

Run shellcheck yourscript in your terminal for instant output, as seen above.

In your editor

You can see ShellCheck suggestions directly in a variety of editors.

Vim, through ALE, Neomake, or Syntastic:

Emacs, through Flycheck or Flymake:

Sublime, through SublimeLinter.
Pulsar Edit (former Atom), through linter-shellcheck-pulsar.
VSCode, through vscode-shellcheck.
Most other editors, through GCC error compatibility.

In your build or test suites

While ShellCheck is mostly intended for interactive use, it can easily be added to builds or test suites. It makes canonical use of exit codes, so you can just add a shellcheck command as part of the process.

For example, in a Makefile:

check-scripts:
    # Fail if any of these files have warnings
    shellcheck myscripts/*.sh

or in a Travis CI .travis.yml file:

script:
  # Fail if any of these files have warnings
  - shellcheck myscripts/*.sh

Services and platforms that have ShellCheck pre-installed and ready to use:

Travis CI
Codacy
Code Climate
Code Factor
Codety via the Codety Scanner
CircleCI via the ShellCheck Orb
Github (only Linux)
Trunk Code Quality (universal linter; allows you to explicitly version your shellcheck install) via the shellcheck plugin
CodeRabbit

Most other services, including GitLab, let you install ShellCheck yourself, either through the system's package manager (see Installing), or by downloading and unpacking a binary release.

It's a good idea to manually install a specific ShellCheck version regardless. This avoids any surprise build breaks when a new version with new warnings is published.

For customized filtering or reporting, ShellCheck can output simple JSON, CheckStyle compatible XML, GCC compatible warnings as well as human readable text (with or without ANSI colors). See the Integration wiki page for more documentation.

Installing

The easiest way to install ShellCheck locally is through your package manager.

On systems with Cabal (installs to ~/.cabal/bin):

cabal update
cabal install ShellCheck

On systems with Stack (installs to ~/.local/bin):

stack update
stack install ShellCheck

On Debian based distros:

sudo apt install shellcheck

On Arch Linux based distros:

pacman -S shellcheck

or get the dependency free shellcheck-bin from the AUR.

On Gentoo based distros:

emerge --ask shellcheck

On EPEL based distros:

sudo yum -y install epel-release
sudo yum install ShellCheck

On Fedora based distros:

dnf install ShellCheck

On FreeBSD:

pkg install hs-ShellCheck

On macOS (OS X) with Homebrew:

brew install shellcheck

Or with MacPorts:

sudo port install shellcheck

On OpenBSD:

pkg_add shellcheck

On openSUSE

zypper in ShellCheck

Or use OneClickInstall - https://software.opensuse.org/package/ShellCheck

On Solus:

eopkg install shellcheck

On Windows (via chocolatey):

C:\> choco install shellcheck

Or Windows (via winget):

C:\> winget install --id koalaman.shellcheck

Or Windows (via scoop):

C:\> scoop install shellcheck

From conda-forge:

conda install -c conda-forge shellcheck

From Snap Store:

snap install --channel=edge shellcheck

From Docker Hub:

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable myscript
# Or :v0.4.7 for that version, or :latest for daily builds

or use koalaman/shellcheck-alpine if you want a larger Alpine Linux based image to extend. It works exactly like a regular Alpine image, but has shellcheck preinstalled.

Using the nix package manager:

nix-env -iA nixpkgs.shellcheck

Using the Flox package manager

flox install shellcheck

Alternatively, you can download pre-compiled binaries for the latest release here:

Linux, x86_64 (statically linked)
Linux, armv6hf, i.e. Raspberry Pi (statically linked)
Linux, aarch64 aka ARM64 (statically linked)
macOS, aarch64
macOS, x86_64
Windows, x86

or see the GitHub Releases for other releases (including the latest meta-release for daily git builds).

There are currently no official binaries for Apple Silicon, but third party builds are available via ShellCheck for Visual Studio Code.

Distro packages already come with a man page. If you are building from source, it can be installed with:

pandoc -s -f markdown-smart -t man shellcheck.1.md -o shellcheck.1
sudo mv shellcheck.1 /usr/share/man/man1

pre-commit

To run ShellCheck via pre-commit, add the hook to your .pre-commit-config.yaml:

repos:
-   repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.11.0
    hooks:
    -   id: shellcheck
#       args: ["--severity=warning"]  # Optionally only show errors and warnings

Travis CI

Travis CI has now integrated ShellCheck by default, so you don't need to manually install it.

If you still want to do so in order to upgrade at your leisure or ensure you're using the latest release, follow the steps below to install a binary version.

Installing a pre-compiled binary

The pre-compiled binaries come in tar.xz files. To decompress them, make sure xz is installed. On Debian/Ubuntu/Mint, you can apt install xz-utils. On Redhat/Fedora/CentOS, yum -y install xz.

A simple installer may do something like:

scversion="stable" # or "v0.4.7", or "latest"
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/${scversion?}/shellcheck-${scversion?}.linux.x86_64.tar.xz" | tar -xJv
cp "shellcheck-${scversion}/shellcheck" /usr/bin/
shellcheck --version

Compiling from source

This section describes how to build ShellCheck from a source directory. ShellCheck is written in Haskell and requires 2GB of RAM to compile.

Installing Cabal

ShellCheck is built and packaged using Cabal. Install the package cabal-install from your system's package manager (with e.g. apt-get, brew, emerge, yum, or zypper).

On macOS (OS X), you can do a fast install of Cabal using brew, which takes a couple of minutes instead of more than 30 minutes if you try to compile it from source.

$ brew install cabal-install

On MacPorts, the package is instead called hs-cabal-install, while native Windows users should install the latest version of the Haskell platform from https://www.haskell.org/platform/

Verify that cabal is installed and update its dependency list with

$ cabal update

Compiling ShellCheck

git clone this repository, and cd to the ShellCheck source directory to build/install:

$ cabal install

This will compile ShellCheck and install it to your ~/.cabal/bin directory.

Add this directory to your PATH (for bash, add this to your ~/.bashrc):

export PATH="$HOME/.cabal/bin:$PATH"

Log out and in again, and verify that your PATH is set up correctly:

$ which shellcheck
~/.cabal/bin/shellcheck

On native Windows, the PATH should already be set up, but the system may use a legacy codepage. In cmd.exe, powershell.exe and Powershell ISE, make sure to use a TrueType font, not a Raster font, and set the active codepage to UTF-8 (65001) with chcp:

chcp 65001

In Powershell ISE, you may need to additionally update the output encoding:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Running tests

To run the unit test suite:

$ cabal test

Gallery of bad code

So what kind of things does ShellCheck look for? Here is an incomplete list of detected issues.

Quoting

ShellCheck can recognize several types of incorrect quoting:

echo $1                           # Unquoted variables
find . -name *.ogg                # Unquoted find/grep patterns
rm "~/my file.txt"                # Quoted tilde expansion
v='--verbose="true"'; cmd $v      # Literal quotes in variables
for f in "*.ogg"                  # Incorrectly quoted 'for' loops
touch $@                          # Unquoted $@
echo 'Don't forget to restart!'   # Singlequote closed by apostrophe
echo 'Don\'t try this at home'    # Attempting to escape ' in ''
echo 'Path is $PATH'              # Variables in single quotes
trap "echo Took ${SECONDS}s" 0    # Prematurely expanded trap
unset var[i]                      # Array index treated as glob

Conditionals

ShellCheck can recognize many types of incorrect test statements.

[[ n != 0 ]]                      # Constant test expressions
[[ -e *.mpg ]]                    # Existence checks of globs
[[ $foo==0 ]]                     # Always true due to missing spaces
[[ -n "$foo " ]]                  # Always true due to literals
[[ $foo =~ "fo+" ]]               # Quoted regex in =~
[ foo =~ re ]                     # Unsupported [ ] operators
[ $1 -eq "shellcheck" ]           # Numerical comparison of strings
[ $n && $m ]                      # && in [ .. ]
[ grep -q foo file ]              # Command without $(..)
[[ "$$file" == *.jpg ]]           # Comparisons that can't succeed
(( 1 -lt 2 ))                     # Using test operators in ((..))
[ x ] & [ y ] | [ z ]             # Accidental backgrounding and piping

Frequently misused commands

ShellCheck can recognize instances where commands are used incorrectly:

grep '*foo*' file                 # Globs in regex contexts
find . -exec foo {} && bar {} \;  # Prematurely terminated find -exec
sudo echo 'Var=42' > /etc/profile # Redirecting sudo
time --format=%s sleep 10         # Passing time(1) flags to time builtin
while read h; do ssh "$h" uptime  # Commands eating while loop input
alias archive='mv $1 /backup'     # Defining aliases with arguments
tr -cd '[a-zA-Z0-9]'              # [] around ranges in tr
exec foo; echo "Done!"            # Misused 'exec'
find -name \*.bak -o -name \*~ -delete  # Implicit precedence in find
# find . -exec foo > bar \;       # Redirections in find
f() { whoami; }; sudo f           # External use of internal functions

Common beginner's mistakes

ShellCheck recognizes many common beginner's syntax errors:

var = 42                          # Spaces around = in assignments
$foo=42                           # $ in assignments
for $var in *; do ...             # $ in for loop variables
var$n="Hello"                     # Wrong indirect assignment
echo ${var$n}                     # Wrong indirect reference
var=(1, 2, 3)                     # Comma separated arrays
array=( [index] = value )         # Incorrect index initialization
echo $var[14]                     # Missing {} in array references
echo "Argument 10 is $10"         # Positional parameter misreference
if $(myfunction); then ..; fi     # Wrapping commands in $()
else if othercondition; then ..   # Using 'else if'
f; f() { echo "hello world; }     # Using function before definition
[ false ]                         # 'false' being true
if ( -f file )                    # Using (..) instead of test

Style

ShellCheck can make suggestions to improve style:

[[ -z $(find /tmp | grep mpg) ]]  # Use grep -q instead
a >> log; b >> log; c >> log      # Use a redirection block instead
echo "The time is `date`"         # Use $() instead
cd dir; process *; cd ..;         # Use subshells instead
echo $[1+2]                       # Use standard $((..)) instead of old $[]
echo $(($RANDOM % 6))             # Don't use $ on variables in $((..))
echo "$(date)"                    # Useless use of echo
cat file | grep foo               # Useless use of cat

Data and typing errors

ShellCheck can recognize issues related to data and typing:

args="$@"                         # Assigning arrays to strings
files=(foo bar); echo "$files"    # Referencing arrays as strings
declare -A arr=(foo bar)          # Associative arrays without index
printf "%s\n" "Arguments: $@."    # Concatenating strings and arrays
[[ $# > 2 ]]                      # Comparing numbers as strings
var=World; echo "Hello " var      # Unused lowercase variables
echo "Hello $name"                # Unassigned lowercase variables
cmd | read bar; echo $bar         # Assignments in subshells
cat foo | cp bar                  # Piping to commands that don't read
printf '%s: %s\n' foo             # Mismatches in printf argument count
eval "${array[@]}"                # Lost word boundaries in array eval
for i in "${x[@]}"; do ${x[$i]}   # Using array value as key

Robustness

ShellCheck can make suggestions for improving the robustness of a script:

rm -rf "$STEAMROOT/"*            # Catastrophic rm
touch ./-l; ls *                 # Globs that could become options
find . -exec sh -c 'a && b {}' \; # Find -exec shell injection
printf "Hello $name"             # Variables in printf format
for f in $(ls *.txt); do         # Iterating over ls output
export MYVAR=$(cmd)              # Masked exit codes
case $version in 2.*) :;; 2.6.*) # Shadowed case branches

Portability

ShellCheck will warn when using features not supported by the shebang. For example, if you set the shebang to #!/bin/sh, ShellCheck will warn about portability issues similar to checkbashisms:

echo {1..$n}                     # Works in ksh, but not bash/dash/sh
echo {1..10}                     # Works in ksh and bash, but not dash/sh
echo -n 42                       # Works in ksh, bash and dash, undefined in sh
expr match str regex             # Unportable alias for `expr str : regex`
trap 'exit 42' sigint            # Unportable signal spec
cmd &> file                      # Unportable redirection operator
read foo < /dev/tcp/host/22      # Unportable intercepted files
foo-bar() { ..; }                # Undefined/unsupported function name
[ $UID = 0 ]                     # Variable undefined in dash/sh
local var=value                  # local is undefined in sh
time sleep 1 | sleep 5           # Undefined uses of 'time'

Miscellaneous

ShellCheck recognizes a menagerie of other issues:

PS1='\e[0;32m\$\e[0m '            # PS1 colors not in \[..\]
PATH="$PATH:~/bin"                # Literal tilde in $PATH
rm “file”                         # Unicode quotes
echo "Hello world"                # Carriage return / DOS line endings
echo hello \                      # Trailing spaces after \
var=42 echo $var                  # Expansion of inlined environment
!# bin/bash -x -e                 # Common shebang errors
echo $((n/180*100))               # Unnecessary loss of precision
ls *[:digit:].txt                 # Bad character class globs
sed 's/foo/bar/' file > file      # Redirecting to input
var2=$var2                        # Variable assigned to itself
[ x$var = xval ]                  # Antiquated x-comparisons
ls() { ls -l "$@"; }              # Infinitely recursive wrapper
alias ls='ls -l'; ls foo          # Alias used before it takes effect
for x; do for x; do               # Nested loop uses same variable
while getopts "a" f; do case $f in "b") # Unhandled getopts flags

Testimonials

At first you're like "shellcheck is awesome" but then you're like "wtf are we still using bash"

Alexander Tarasikov, via Twitter

Ignoring issues

Issues can be ignored via environmental variable, command line, individually or globally within a file:

https://github.com/koalaman/shellcheck/wiki/Ignore

Reporting bugs

Please use the GitHub issue tracker for any bugs or feature suggestions:

https://github.com/koalaman/shellcheck/issues

Contributing

Please submit patches to code or documentation as GitHub pull requests! Check out the DevGuide on the ShellCheck Wiki.

Contributions must be licensed under the GNU GPLv3. The contributor retains the copyright.

Copyright

ShellCheck is licensed under the GNU General Public License, v3. A copy of this license is included in the file LICENSE.

Happy ShellChecking!

Other Resources

The wiki has long form descriptions for each warning, e.g. SC2221.
ShellCheck does not attempt to enforce any kind of formatting or indenting style, so also check out shfmt!

IntersectMBO/cardano-node

The core component that is used to participate in a Cardano decentralised blockchain.

`cardano-node`

The cardano-node repository is the point of integration of the ledger, consensus, networking layers. It provides the cardano-node executable which is used to participate in the Cardano network.

This is an approximate diagram of the dependencies among the different components:

stateDiagram-v2
    cn: cardano-node
    tr: trace-dispatcher/iohk-monitoring-framework
    ca: cardano-api
    co: ouroboros-consensus
    on: ouroboros-network
    cl: cardano-ledger
    p: plutus
    cn --> ca
    cn --> tr
    ca --> co
    ca --> on
    co --> on
    co --> cl
    ca --> cl
    cl --> p

Instructions

The process for getting a cardano-node executable can be found in the Cardano Developer Portal.

The configuration and files required to run a cardano-node in one of the supported networks are described also in the Cardano Developer Portal.

Using `cardano-node` and dependencies as a library

The API documentation is published on the webpage. If you want to use the cardano-node Haskell packages from another Haskell project, you should set up CHaP to get the packages defined in this repository.

Troubleshooting

For some troubleshooting help with building or running cardano-node, the wiki has a troubleshooting page that documents some common gotchas.

IntersectMBO/cardano-ledger

The ledger implementation and specifications of the Cardano blockchain.

Cardano Ledger

This repository contains the formal specifications, executable models, and implementations of the Cardano Ledger.

The documents can be accessed using the following links:

Era	Design Documents	Formal Specification	CDDL
Byron		Chain Spec, Ledger Spec	CDDL, PDF
Shelley	Design	Spec	CDDL
Allegra	Same as Mary era below	Same as Mary era below	CDDL
Mary	Multi-Currency, UTXOma	Spec	CDDL
Alonzo	eUTXO	Spec	CDDL
Babbage	batch-verification, CIP-31, CIP-32, CIP-33	Spec	CDDL
Conway	CIP-1694	Spec	CDDL

Note that the formal specification documents present the specification in a diff-style manner. That is, each document shows specification changes with respect to documents of previous eras.

There is an ongoing effort to provide a full machine-verified formal specification of the Cardano Ledger that will subsume the (formal specification) documents listed above. This effort is complete for Conway but partially complete for previous eras.

Repository structure

The directory structure of this repository is as follows:

Byron
- ledger
- chain
  - formal-spec
  - executable-spec
Shelley
- design-spec
- formal-spec
- implementation
- tests
- cddl
Allegra - Timelocks
Mary - Multi-Assets
Alonzo - Smart Contracts
- formal-spec
- implementation
- cddl
- tests
Babbage
- formal-spec
- implementation
- cddl
- tests
Conway - Governance
- formal-spec
- implementation
- cddl
- tests
Libraries

Building

It is recommended to use nix for building everything in this repository. Make sure you have a recent version of nix by following this guide.

Haskell files can be built with cabal inside of a nix shell, which can be entered by invoking nix develop from the root directory.

Nix Cache

When using nix it is recommended that you setup the cache, so that it can reuse built artifacts, reducing the compilation times dramatically:

If you are using NixOS add the snippet below to your /etc/nixos/configuration.nix:

nix.settings = {
  experimental-features = [ "nix-command" "flakes" ];
  substituters = [
    "https://cache.nixos.org"
    "https://cache.iog.io"
  ];
  trusted-public-keys = [
    "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
  ];
};

If you are using the nix package manager next to another operating system put the following in /etc/nix/nix.conf:

experimental-features = nix-command flakes
substituters        = https://cache.iog.io https://cache.nixos.org/
trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

Building the LaTeX documents and executable specifications

When using nix the documents and Haskell code can be readily built by running:

nix build .#specs

The LaTeX documents will be placed inside a directory named result, e.g.:

result/byron-ledger.pdf
result/shelley-delegation.pdf
result/non-integer-calculations.pdf
result/small-step-semantics.pdf
result/shelley-ledger.pdf
result/byron-blockchain.pdf

Building individual LaTeX documents

Change to the latex directory where the latex document is (e.g. eras/shelley/formal-spec for the ledger specification corresponding to the Shelley release, or eras/byron/ledger/formal-spec for the ledger specification corresponding to the Byron release). Then, build the latex document by running:

cd <myLaTexDir>
nix develop --command make

For a continuous compilation of the LaTeX file run:

cd <myLaTexDir>
nix develop --command make watch

Testing

From the root directory invoke nix develop to enter a nix shell, then run cabal test all to run all tests or cabal test <package> to run the tests for a specific package.

Note: The CARDANO_MAINNET_MIRROR environment variable can be overridden in flake.nix if one desires to run the Byron tests with a different version of the mainnet epochs.

Submitting an issue

Issues can be filed in the GitHub Issue tracker.

However, note that this is pre-release software, so we will not usually be providing support.

Contributing

See CONTRIBUTING.

Using `git fsck`

There's some ancient history in the repo that causes git fsck version 2.44.0 or later to report errors when running semantic checks on an old version of the .gitmodules file.

This can be overcome by running git config fsck.skipList .git-fsck-skiplist once, sometime after cloning.

However, the problem prevents cloning if you have transfer.fsckObjects enabled in your global git configuration. You can overcome this by downloading the skiplist file before you clone and then specifying it in a config option to the clone command:

$ curl -sSLO https://raw.githubusercontent.com/IntersectMBO/cardano-ledger/refs/heads/master/.git-fsck-skiplist
$ git clone -c fetch.fsck.skipList=.git-fsck-skiplist ...
...
$ rm .git-fsck-skiplist

digital-asset/cn-quickstart

Accelerate building apps on Canton Network using this quickstart to start quick!

Canton Network application quickstart

Note: On July 2, 2025, the quickstart underwent an architectural change and no longer connects to DevNet. This update may require a make clean-all to remove old data and then a make build.

This project provides scaffolding to develop a Canton Network (CN) application for the Global Synchronizer. We intend that you clone the repository and incrementally update the solution to match your business operations. We assume that you have a Daml Enterprise license to leverage all of this project's features at runtime. However, an OSS developer can benefit from this project by understanding how a CN Global Synchronizer application is structured.

Binaries terms and conditions.

Licensed under the BSD Zero Clause License.

Disclaimer

Once you are familiar with the Quickstart Application, review the technology choices and the application design to determine what changes are needed. These decisions are up to you. The CN Quickstart is a rapidly evolving work in progress.

Docs and guides

You can find Quickstart documentation in the Canton Network documentation portal.

Technical documentation

This project is rapidly enhanced, so please check back often for updates.

Setup

See the Quickstart Installation Guide for installation and setup directions.

Quickstart

To start the application:

# In the local repository directory
$ direnv allow
$ cd quickstart

# Setup your quickstart environment
$ make setup

# Build the application
$ make build

# Start the application, Canton services, and Observability (if enabled)
$ make start

# In a separate shell - run a Canton Console for the App Provider
$ make canton-console

# In a separate shell - run Daml Shell
$ make shell

An assistant helps set up deployment when running make start for the first time. You can choose to run the application in standard mode or test mode and with or without OAUTH2. You may change this later by running make setup.

Debugging TL;DR

If a container fails to start, there are a few things to try:

Ensure Docker Compose is configured to allocate enough memory. The recommended minimum total memory is 8 GB.
Start fresh with make clean-all and then manually delete all Docker images and volumes.

Note: The CN Quickstart uses Java SDK version Eclipse Temurin JDK version 21 which runs within the Docker container. This information is specified in quickstart/compose.yaml and .env.

If you need assistance, please follow these directions to gather the log information needed for debugging:

make setup # optional
make clean-all # remove data from prior runs
make capture-logs # this needs to be done in a separate terminal because it will block and keep running. Use <ctrl-c> to stop
make start # start the system with logging enabled
tar -czvf <your file name with .tar.gz> logs # gather the content of the logs directory into a file

Available make targets

Run make help to see a list of all available targets. Read the FAQ Make target reference for a detailed list of make targets and their descriptions.

Topology

Quickstart is built on top of https://github.com/hyperledger-labs/splice/tree/main/cluster/compose/localnet. Check documentation for more information about Splice LocalNet.

This diagram summarizes the relationship of services that are started as part of make start. The canton and splice services are configured to serve multiple logically separate components (each component represented with a box in the diagram) from a single container to reduce resource consumption. Similarly the postgres service contains multiple databases required by Quickstart services. One nginx service is used as proxy for all Quickstart services that needs one except for keycloak that has its own nginx-keycloak as it needs to be ready before other services start. The focus of Canton Network Quickstart is to provide a development environment for App Providers.

For more information and detailed diagrams, please refer to the Topology documentation.

Accessing frontends

After starting the application with make start you can access the following UIs:

Application UIs

App User ANS UI
- URL: http://ans.localhost:2000
- Description: Interface for registering names.
App Provider ANS UI
- URL: http://ans.localhost:3000
- Description: Interface for registering names.
Application user frontend
- URL: http://app-provider.localhost:3000
- Description: The main web interface of the application.
App user wallet UI
- URL: http://wallet.localhost:2000
- Description: Interface for managing user wallets.
App provider wallet UI
- URL: http://wallet.localhost:3000
- Description: Interface for managing user wallets.

Super Validator UIs (if LocalNet enabled via `make setup`)

Super Validator web UI
- URL: http://sv.localhost:4000
- Description: Interface for super validator functionalities.
Scan Web UI
- URL: http://scan.localhost:4000
- Description: Interface to monitor transactions.
Note: LocalNet rounds may take up to 6 rounds (equivalent to one hour) to display in the scan UI.

The *.localhost domains will resolve to your local host IP 127.0.0.1.

External Token Transfers

For external integrations requiring token transfers, the system uses Registry API endpoints rather than direct contract queries. Unlike direct contract access, external token transfers are handled through Registry API endpoints exposed by the Scan app.

LocalNet Endpoint: Transfer Factory: http://scan.localhost:4000/registry/transfer-instruction/v1/transfer-factory

Exploring Quickstart Docker Compose

Before exploring advanced topics, we recommend familiarizing yourself with the core components of the Licensing Model Workflow within Quickstart. In particular, the implementation of the backend-service serves as an excellent entry point.

If you have already explored the Quickstart web UI and would now like to understand how the Quickstart Docker Compose configuration is orchestrated, start by running a simple setup using make setup with Observability and OAuth2 disabled. Then, execute the following command to inspect the resolved configuration for the backend service:

make compose-config | tail -n +2 | yq eval '.services.backend-service'

This command outputs a configuration similar to the example below:

command:
  - /app/start.sh
container_name: backend-service
depends_on:
  pqs-app-provider:
    condition: service_started
    required: true
  splice-onboarding:
    condition: service_healthy
    required: true
environment:
  _JAVA_OPTIONS: -XX:-UseCompressedOops -Xms512m -Xmx700m
  AUTH_APP_PROVIDER_BACKEND_USER_NAME: app-provider-backend
  BACKEND_PORT: "8080"
  LEDGER_HOST: canton
  LEDGER_PORT: "3901"
  POSTGRES_DATABASE: pqs-app-provider
  POSTGRES_HOST: postgres
  POSTGRES_PASSWORD: supersafe
  POSTGRES_PORT: "5432"
  POSTGRES_USERNAME: cnadmin
  SPRING_PROFILES_ACTIVE: shared-secret
  VALIDATOR_URI: http://splice:3903/api/validator
image: eclipse-temurin:17.0.12_7-jdk
labels:
  description: 'Backend service supporting the Quickstart Licensing workflow. Note: The APP_PROVIDER_PARTY environment variable is dynamically resolved at runtime before the main process is initiated.'
mem_limit: "1073741824"
networks:
  default: null
ports:
  - mode: ingress
    target: 8080
    published: "8080"
    protocol: tcp
volumes:
  - type: bind
    source: /repositories/cn-quickstart/quickstart/backend/build/distributions/backend.tar
    target: /backend.tar
    bind:
      create_host_path: true
  - type: bind
    source: /repositories/cn-quickstart/quickstart/docker/backend-service/start.sh
    target: /app/start.sh
    bind:
      create_host_path: true
  - type: volume
    source: onboarding
    target: /onboarding
    volume: {}
working_dir: /app

This configuration demonstrates how the backend-service relies on the Quickstart-provided infrastructure. Quickstart automates much of the local environment setup for LocalNet, allowing you to prioritize application development. As you progress toward deployment and explore cloud orchestration, a deeper grasp of service configuration is invaluable. For now, consider these services a ready-to-use infrastructure foundation.

Then explore register-app-user-tenant, the service that registers AppUser tenants to the backend-service. This allows end users from the AppUser organization to log in and quickly start the web UI. That, in turn, ties the AppUser Identity Provider to the AppUser primary party ID. If the end user is logged in through this Identity Provider, the user can then act as the AppUser primary party. The register-app-user-tenant service utilizes functionality provided by the splice-onboarding module to make the task as simple as possible.

This step can also be performed manually through the web UI if you log in to Quickstart as app-provider and navigate to the tenants tab. At that tab, you can also see a list of registered tenants and verify that the AppUser tenant was automatically pre-registered for you by register-app-user-tenant.

Once you run make create-app-install-request, the docker/create-app-install-request service executes a script that initiates the Licensing workflow on behalf of the app-user. This script leverages the capabilities of the splice-onboarding module to streamline the process. In a production environment, the initial Licensing workflow step would be executed by submitting a command to the AppUser Participant Node, potentially supported by a dedicated web UI within the AppUser infrastructure.

Authorization

Quickstart support to different authorization modes:

oauth2 (default)
shared-secret See Splice LocalNet documentation for the shared-secret mode which is default Splice LocalNet auth mode.

OAuth2 mode - keycloak setup

To perform operations such as creating AppInstallRequest and renewing License, users must be authenticated and authorized. The endpoints that perform these operations are protected by OAuth2 Authorization Code Grant Flow. GRPC communication between the backend service and participant is secured by OAuth2 Client Credentials Flow.

In OAuth2 mode, Quickstart starts a local multi-tenant instance of keycloak. Two registered tenants are AppProvider and AppUser. Tenants have pre-configured users app-provider and app-user, as well as clients needed for validator, wallet, pqs, frontend, and backend service. Pre-configured users, clients, and realms are imported from the docker/compose/modules/keycloak/conf/data folder on Keycloak startup. The configuration in that folder is exported from the Keycloak instance after manual configuration via Keycloak Administration Console by running commands

/opt/keycloak/bin/kc.sh export --dir=/opt/keycloak/data/import --realm AppUser --optimized
/opt/keycloak/bin/kc.sh export --dir=/opt/keycloak/data/import --realm AppProvider --optimized

Pre-configured users, clients and realms are used directly in Quickstart components and via environment variables. Each component, module or backend-service refers to the pre-configured values in its environment variables. e.g. docker/modules/keycloak/env/app-provider/on/oauth2.env, docker/backend-service/onboarding/env/oauth2.env

Backend service tenant registration

Only the end users from an organization registered using endpoint http://backend-service:${BACKEND_PORT}/admin/tenant-registrations can log into the Quickstart web UI. The AppUser organization is registered on the Quickstart startup by calling the registration script in the register-app-user-tenant Docker container.

Port mappings

Web UIs

Service	Port	URL Pattern	Description
App User UI	2000	`*.localhost:2000`	App User wallet & ANS interfaces
App Provider UI	3000	`*.localhost:3000`	App Provider & application frontend
SV UI	4000	`*.localhost:4000`	Super Validator, Scan & SV web UIs
Swagger UI: External	9090	`localhost:9090`	API documentation browser (host access)
Swagger UI: Internal	8080	-	API documentation browser (container)

Application services

Service	Port	Description
Backend Service	8080	Spring Boot backend for Licensing workflow
Backend Debug (JVM)	5005	Remote JVM debugging (when `DEBUG_ENABLED=true`)

Canton Participant Ledger API

Role	Port	Description
SV Participant	4901	Super Validator Ledger API
App Provider Participant	3901	App Provider Ledger API
App User Participant	2901	App User Ledger API

Canton Participant admin API

Role	Port	Description
SV Participant	4902	Super Validator Admin API
App Provider Participant	3902	App Provider Admin API
App User Participant	2902	App User Admin API

Canton JSON API (HTTP Ledger API)

Role	Port	Description
SV Participant	4975	Super Validator JSON API
App Provider Participant	3975	App Provider JSON API
App User Participant	2975	App User JSON API

Splice Validator admin API

Role	Port	Description
SV Validator	4903	Super Validator Admin API
App Provider Validator	3903	App Provider Validator Admin API
App User Validator	2903	App User Validator Admin API

Database

Service	Port	Description
PostgreSQL	5432	Multi-database PostgreSQL instance

Authentication (When OAuth2 enabled)

Service	External port	Internal port	Description
Keycloak (via nginx)	8082	8082	Identity Provider for OAuth2
Keycloak Health	-	9000	Internal health check endpoint

Observability stack

Service	External port	Internal port	Description
Grafana	3030	3000	Metrics & logs dashboard
OTEL Collector (OTLP)	-	14001	OpenTelemetry OTLP receiver
OTEL Collector (Fluentd)	14002	14002	Log collection endpoint
Prometheus	-	14011	Metrics storage & query
Loki	-	14012	Log aggregation
Tempo (OTLP)	-	14013	Trace collection
Tempo (HTTP)	-	14014	Trace query API
Canton Metrics	-	14021	Canton metrics endpoint
cAdvisor	-	14022	Container metrics
Postgres Exporter	-	14023	PostgreSQL metrics
Nginx Exporter	-	14024	Nginx metrics

Port suffix scheme

Quickstart uses a port suffix scheme for participant/validator services:

Suffix	Service type
901	Ledger API
902	Admin API
903	Validator Admin API
961	gRPC Health Check
975	JSON API
900	HTTP Health Check

Prefix convention:

4xxx = Super Validator (SV)
3xxx = App Provider
2xxx = App User

Localhost domain mappings

URL	Port	Service
http://wallet.localhost:2000	2000	App User Wallet UI
http://ans.localhost:2000	2000	App User ANS UI
http://wallet.localhost:3000	3000	App Provider Wallet UI
http://ans.localhost:3000	3000	App Provider ANS UI
http://app-provider.localhost:3000	3000	Application Frontend
http://sv.localhost:4000	4000	SV Web UI
http://scan.localhost:4000	4000	Scan Web UI
http://keycloak.localhost:8082	8082	Keycloak Admin Console
http://app-provider.localhost:5173	5173	Vite Dev Server (development)

Docker Compose-based development for LocalNet

Quickstart leverages Docker Compose for modular development. Instead of relying on a single extensive docker-compose.yaml file, this approach orchestrates multiple compose files and corresponding environment files for each Quickstart module. Splice LocalNet is housed within the docker/modules/localnet directory. In the Makefile, Docker Compose commands are dynamically assembled from Splice LocalNet, Quickstart modules, and Quickstart-specific compose and environment files, arranged in an order that respects the interdependencies of the various components.

Some modules (e.g., Keycloak and Observability) are optional and can be toggled on or off based on your selections made during make setup. When the Docker Compose command is executed, it merges all specified Compose YAML files in the order they appear on the command line. Likewise, the environment is built by applying each environment file in sequence; if the same variable is defined in multiple files, the value from the later file will overwrite the previous ones.

The splice-onboarding module supports two distinct operational modes. Initially, it performs a one-time setup procedure for Canton, Splice and modules. This initialization includes creating a ledger user and assigning necessary permissions. Developers can customize this process by specifying DAR files (and mounting it to file in /canton/dars in splice-onboarding) for ledger upload, custom shell scripts, or environment variables through their project’s compose.yaml file. For example:

splice-onboarding:
  env_file:
    - ./docker/backend-service/onboarding/env/${AUTH_MODE}.env
  volumes:
    - ./docker/backend-service/onboarding/onboarding.sh:/app/scripts/on/backend-service.sh
    - ./daml/licensing/.daml/dist/quickstart-licensing-0.0.1.dar:/canton/dars/quickstart-licensing-0.0.1.dar

Developers may want to leverage the splice-onboarding module to execute custom onboarding scripts once all dependent services are operational (for instance, the register-app-user-tenant script) or to initialize specific workflows (such as scripts defined in /docker/create-app-install-request/compose.yaml).

By integrating this approach, developers can leverage prepopulated environment variables, such as APP_PROVIDER_PARTY and other authentication-related settings, while also accessing a suite of tools bundled with the splice-onboarding container. These tools, including utilities like curl, jq, and jwt-cli, together with an library of shell functions found in docker/modules/splice-onboarding/docker/utils.sh that demonstrate on how to utilize JSON Ledger API HTTP endpoints effectively. This comprehensive setup facilitates the achievement of necessary functionality with minimal additional configuration.

Utilizing Docker Compose’s merge mechanism, developers have complete control over the configuration. They can add any settings by providing a custom compose.yaml (which is usually the first file processed in the Docker Compose command) or by appending a compose.override.yaml file at the end to override default configurations defined by Splice LocalNet or Quickstart modules.

Please note that while Quickstart is designed to streamline local development, deploying to production requires additional considerations. In the Quickstart demo, the splice-onboarding component facilitates initialization, onboarding, and the execution of scripts that drive the demonstration workflows. However, this component is not intended for use in a production environment. In a production-grade environment, you would typically utilize an orchestration framework such as Kubernetes and replace certain automated configurations with controlled, manual configuration steps. This approach enhances security and clearly separates services in line with enterprise standards.

Modules

The Quickstart repository includes modular components that can be reused in developer projects outside of Quickstart. These modules are located in the docker/modules directory by default, however, they can be sourced from any directory by setting the MODULES_DIR environment variable accordingly.

Splice LocalNet is a special module borrowed from the Splice repository and is placed by default in docker/modules. It can also be relocated by properly configuring the LOCALNET_DIR environment variable.

Each module provides specific functionality and may depend on other modules. The currently supported modules are:

keycloak (optional): Adds support for OAuth2 authorization to Splice LocalNet.
splice-onboarding: Provides onboarding capabilities, including a collection of tools, resolved environment settings, and shell scripts for calling JSON Ledger API HTTP endpoints.
pqs: Offers preconfigured PQS instances for Splice LocalNet participants.
observability: Introduces observability infrastructure components.
daml-shell: A standalone module that enables launching Daml Shell. By default, it connects to the pqs-app-provider’s Postgres database.

Docker Profiles

Docker profiles are used in both Splice LocalNet and Quickstart to enable or disable specific functionalities. Each module can support multiple profiles. For example, Splice LocalNet defines the following five profiles:

app-provider
app-user
sv
swagger-ui
console

The console module runs as a standalone container, while the other modules start by default unless explicitly disabled (e.g., by omitting the profile flag such as --profile app-provider). In some implementations, modules rely on environment variables to determine the active profiles. In these cases, you should set the corresponding environment variable—such as APP_PROVIDER_PROFILE—to either "on" or "off". This approach is necessary because Docker does not inherently expose profile configuration details within the Docker Compose file or inside the container environments.

Environment

There are two distinct types of environment files:

Files used primarily for Docker Compose configuration.
Files intended for Docker container environment settings.

The first category includes files such as .env, .env.local, ${LOCALNET_DIR}/env/common.env, and any compose.env files from the modules. The second category encompasses the remaining files found under ${LOCALNET_DIR}/env as well as the env directories within the modules.

In the Docker container environment files, you can reference variables defined in the Docker Compose environment. Simply declare a variable as VAR=${VAR} to ensure that the value from the Docker Compose environment is available within the container.

Dynamic Configuration

In certain situations, it is necessary to share runtime information between services. For instance, in the case of the backend-service, the environment variable APP_PROVIDER_PARTY is mandatory. In a production-like environment, this information would typically be provided manually by a system administrator. The party ID becomes available only after the complete initialization of Canton/Splice. To automate this process, one might consider retrieving the party ID by querying the JSON Ledger API HTTP endpoint; however, adding extra environment variables to support JWT token retrieval for this purpose could clutter the backend service configuration.

A preferable solution is to leverage the existing splice-onboarding service, which already possesses the appropriate environment and tools to perform this task. By mounting a custom script into the splice-onboarding container (for example, mapping ./docker/backend-service/onboarding/onboarding.sh to /app/scripts/on/backend-service.sh), the splice-onboarding service executes the script (or any script located in the /app/scripts/on/ directory) at the conclusion of its initialization routine.

Within the script, the acquired information can be shared with the backend service as follows:

  share_file "backend-service/on/backend-service.sh" <<EOF
  export APP_PROVIDER_PARTY=${APP_PROVIDER_PARTY}
EOF

In this context, share_file is a utility function that writes the provided content (the second argument) to the specified file (the first argument) on the shared volume onboarding. This volume is also mounted in the backend-service, and the startup script (docker/backend-service/start.sh) sources the newly shared script prior to executing the main command of the backend service, thereby ensuring that the APP_PROVIDER_PARTY environment variable is available to the service.

Local Development

Frontend

Restart frontend

Run:

make restart-frontend

This target restarts the frontend and handles any required rebuilds.

Vite development

Use Vite's hot-module reloading for fast UI iteration:

make start-vite-dev

or, if Quickstart is already running:

make vite-dev

Open the app at: http://app-provider.localhost:5173

Note: Use the same host/port so OAuth redirects (Keycloak) continue to work.

Debugging in VS Code

Create or update quickstart/frontend/.vscode/launch.json with:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Vite: Chrome Debug",
      "type": "chrome",
      "request": "launch",
      "url": "http://app-provider.localhost:5173",
      "webRoot": "${workspaceFolder}/quickstart/frontend/src"
    }
  ]
}

This launches Chrome against the Vite server and maps breakpoints to your source files. If you change user sessions (login/logout) or Keycloak redirects occur, reload the page so VS Code can resolve sources.

Backend service

Restart backend

Run:

make restart-backend

This target restarts the backend, handles dependent services (e.g., register-app-user-tenant), and rebuilds the service if needed.

Debug backend service

Enable remote JVM debugging by setting:

export DEBUG_ENABLED=true
make restart-backend

This opens port 5005. Use the following JVM agent options for your remote debugger:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005

Configure your IDE (IntelliJ, VS Code) to attach to port 5005 for step-through debugging.

Example in IntelliJ Idea

Viewing logs

For interactive local log inspection we recommend lnav (https://lnav.org/). Install the Canton log format and use it to view *.clog files. Example Canton lnav format definition: https://github.com/hyperledger-labs/splice/blob/main/canton/canton-json.lnav.json

Open the logs directory with lnav to filter and analyze logs efficiently.

License

You may use the contents of this repository in parts or in whole according to the 0BSD license.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

halogenandtoast/ArkhamHorror

An unofficial rules-compliant browser based version of Arkham Horror: The Card Game. Not produced, endorsed, or supported by, or affiliated with Fantasy Flight Games.

Arkham Horror LCG

The goal of this project is to implement a web version of Arkham Horror with as many of the rules implemented as possible.

Warning

This is very much a work in progress. Things may break at any time, but if they do, please file a bug.

Features

Multiplayer up to 4 players
Multiplayer solitaire
Tarot Readings
Deck import from ArkhamDB and arkham.build

Finished Content

Player Cards

All player cards before 2026

Campaigns

Night of the Zealot
- Return to Night of the Zealot
The Dunwich Legacy
- Return to The Dunwich Legacy
The Path To Carcosa
- Return to The Path To Carcosa
The Forgotten Age
- Return to The Forgotten Age
The Circle Undone
- Return to The Circle Undone
The Dream-Eaters
The Innsmouth Conspiracy
Edge of the Earth

Side Stories

The Curse of the Rougarou
Carnevale of Horrors
Murder at the Excelsior Hotel
The Midwinter Gala
Film Fatale

I just want to try this out on my computer

Linux Users

Install Docker, then run:

curl -fsSL https://raw.githubusercontent.com/halogenandtoast/ArkhamHorror/main/install.sh | bash

This creates an arkham-horror/ directory, downloads the required files, generates a database password, and starts the app. Open http://localhost:3000 when it's done.

The script will ask if you want to download game images (~2.9 GB). If you skip this step, the app loads images from the CDN automatically — no extra setup needed.

Windows Users

Install Docker, specifically the version of Docker known as Docker Desktop.
Install a "terminal only" version of Ubuntu that can be run inside of Windows, for which the easiest available method is to install from the Microsoft Store. You may choose any Linux distro other than Ubuntu if you know what you are doing.
In Docker Desktop, go to Settings > Resources > WSL Integration and enable integration with Ubuntu Linux distro that you installed in the previous step. This allows us to access Docker from inside Ubuntu.

Start the Ubuntu terminal and run:

curl -fsSL https://raw.githubusercontent.com/halogenandtoast/ArkhamHorror/main/install.sh | bash

The app should start being served at http://localhost:3000, if nothing went wrong.
Every time you want to start the app, you can use docker compose up
If you get around to figuring out how to use Docker Desktop, you could also press buttons to start and stop the app instead of typing commands to run it.

Things that can go wrong

If the app doesnt start at all, or it starts but you cannot create a user account, or any other issue due to Murphy's Law, you have to check the logs of the Docker container to find the error messages. In Docker Desktop, you can access this by clicking on the arkham-horror "compose stack" found in the Containers list.

Possible problems:

Problem	Solution
Error involving `docker-credential-desktop.exe`	Try restarting your computer
When clicking on the "REGISTER" button, the error `password authentication failed` is logged	Stop the app using `docker compose down` and then refetch the app using `docker compose pull`

Manual setup (alternative)

If you prefer not to use the install script, you'll need four files:

mkdir -p arkham-horror/config arkham-horror/scripts arkham-horror/frontend/public/img
cd arkham-horror
curl -fsSL https://raw.githubusercontent.com/halogenandtoast/ArkhamHorror/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/halogenandtoast/ArkhamHorror/main/setup.sql -o setup.sql
curl -fsSL https://raw.githubusercontent.com/halogenandtoast/ArkhamHorror/main/scripts/fetch-assets.sh -o scripts/fetch-assets.sh
# Generate a strong password
openssl rand -base64 32 > config/postgres_password.txt
docker compose up -d

The app automatically detects whether local images are present:

No local images (default after install) → images load from the CDN automatically
Local images present (after running the fetch service) → images served locally

To fetch images locally, use the fetch-images Docker service. Once fetched, restart with docker compose restart web and the app will switch to local images.

# English only (~1.3 GB) — portraits, tokens, icons, card images
docker compose --profile fetch-images run --rm fetch-images en

# English + a specific language (recommended for non-English play)
docker compose --profile fetch-images run --rm fetch-images en+fr   # French
docker compose --profile fetch-images run --rm fetch-images en+es   # Spanish
docker compose --profile fetch-images run --rm fetch-images en+ita  # Italian
docker compose --profile fetch-images run --rm fetch-images en+ko   # Korean
docker compose --profile fetch-images run --rm fetch-images en+zh   # Chinese

# A single language's card translations only (English assets still load from CDN)
docker compose --profile fetch-images run --rm fetch-images fr

# Everything (~2.9 GB)
docker compose --profile fetch-images run --rm fetch-images all

Images are stored in frontend/public/img/ and mounted into the container. After fetching, run docker compose restart web to pick them up.

To switch back to CDN at any time, add this to the web service environment in docker-compose.yml:

    environment:
      - ASSET_HOST=https://assets.arkhamhorror.app

Updating

docker compose pull
docker compose up -d

Local dev

Dependencies

Stack for GHC
Node
Postgresql
Sqitch (optional: for migrations)

Local Setup

Running via Docker

The image is setup to use an external database passed via the DATABASE_URL environment variable. Follow the steps below to setup the database and then run the following commands

docker build -t arkham .
docker run -t -i -e PORT=3000 -e DATABASE_URL="postgres://docker:docker@host.docker.internal:5432/arkham-horror-backend" -p 3000:3000 arkham

Backend

Run stack setup in the backend directory, then run stack build --fast (note: this will still take a long time)

Frontend

Run npm install in the frontend directory

Images

Image assets (~2.9 GB) are not stored in the git repository. They are hosted on CloudFront and the app loads them from the CDN by default in both development and production — no extra setup needed.

If you need local copies (e.g. for offline development), use the fetch script (requires aws CLI and curl):

make fetch-images     # Everything (~2.9 GB)
make fetch-cards      # English card images only (~755 MB)

# Or use the script directly:
./scripts/fetch-assets.sh en        # All English/static images (~1.3 GB)
./scripts/fetch-assets.sh en+fr     # English + French (recommended for French play)
./scripts/fetch-assets.sh en+es     # English + Spanish
./scripts/fetch-assets.sh en+ita    # English + Italian
./scripts/fetch-assets.sh en+ko     # English + Korean
./scripts/fetch-assets.sh en+zh     # English + Chinese
./scripts/fetch-assets.sh fr        # French card translations only

If you only have Docker (no local AWS CLI), use the Docker-based targets instead:

make fetch-images-docker    # Everything via Docker (~2.9 GB)
make fetch-cards-docker     # English card images only via Docker

# Or run directly with the same targets as above:
docker compose --profile fetch-images run --rm fetch-images en
docker compose --profile fetch-images run --rm fetch-images en+fr
docker compose --profile fetch-images run --rm fetch-images fr

To use local images instead of CDN in local dev, create frontend/.env.development.local:

VITE_ASSET_HOST=

To revert to CDN, remove the file or set VITE_ASSET_HOST=https://assets.arkhamhorror.app.

If you add new images, sync them to S3 and regenerate the manifest:

make sync-and-manifest

To install a git hook that warns if you forget to update the manifest:

make install-hooks

Database

Create the local database:

createdb arkham-horror-backend
cd migrations
sqitch deploy db:pg:arkham-horror-backend

If you do not have sqitch you can cat migrations/deploy/* to see the create table statements and run them manually, you will want to specifically run the users and arkham_games create table statements first.

Running the server

start the backend with cd backend && make api.watch
start the frontend with cd frontend && npm run serve

Copyright Disclaimer

The information presented in this app about Arkham Horror: The Card Game™, both textual and graphical, is © Fantasy Flight Games 2024. This app is a fan project and is not produced, endorsed, or supported by, or affiliated with Fantasy Flight Games.

All artwork and illustrations are the intellectual property of their respective creators. All Arkham Horror: The Card Game™ images and graphics are copyrighted by Fantasy Flight Games.

mtolly/onyx

Toolkit for converting and building songs for Rock Band, Guitar Hero, Clone Hero, and other similar rhythm games

Onyx Music Game Toolkit

I transcribe songs for use in Harmonix's Rock Band 3 and other similar rhythm games. Along the way, I've written a helpful program to streamline the build process, and do all sorts of useful conversions and transformations.

Download from the releases page.

Onyxite's Custom Songs

This repository contains the "source" for charts which (once finished) are available from my thread on the Customs Creators forum, or from my own website (work in progress).

Licensing

The Onyx software is free software via the GNU GPL v3.

My transcriptions (not the compositions) are freely licensed under Creative Commons Attribution-ShareAlike. All compositions are the property of the original artists.

In addition to my own charts, this repository contains work by several other authors, including: Harmonix, Grinnz, mazegeek999, TheLieInKing, and more. (Credited in individual song READMEs.) Other authors' work hosted here is not necessarily licensed in the same way; please contact them if you want permission to redistribute or repackage charts.

b3nj5m1n/xdg-ninja

A shell script which checks your $HOME for unwanted files and directories.

xdg-ninja

Because you wouldn't let just anyone into your $HOME

A shell script that checks your $HOME for unwanted files and directories.

When xdg-ninja encounters a file or directory it knows about, it will tell you whether it's possible to move it to the appropriate location, and how to do it.

The configurations are from the arch wiki page on XDG_BASE_DIR, antidot (thanks to Scr0nch for writing a conversion tool), and crowdsourced by other users.

Installing

Manual Installation

Clone the repository, then run the ./xdg-ninja.sh script.

git clone https://github.com/b3nj5m1n/xdg-ninja
cd xdg-ninja
./xdg-ninja.sh

This will run every test in the default configuration.

Nix

Turn on flakes, then run the following command:

nix run github:b3nj5m1n/xdg-ninja

Homebrew

Note

Due to how xdg-ninja is developed, releases are not cut, so Homebrew ships a stale version, therefore you have to install and upgrade xdg-ninja from the git HEAD. ref: #204

Homebrew will not upgrade xdg-ninja when running a generic brew upgrade, you must specifically upgrade xdg-ninja from the git HEAD, see below

Install:

brew install xdg-ninja --HEAD

Upgrade:

brew upgrade xdg-ninja --fetch-HEAD

Other Package Managers

xdg-ninja is available in many other package managers.

The full list is available on the repology page.

Follow the instructions for your package manager to install xdg-ninja.

Contributing

Dependencies

Your favorite POSIX-compliant shell (bash, zsh, dash, etc.)
jq for parsing the json files
find

Optional

glow for rendering Markdown in the terminal (bat, pygmentize or highlight can be used as a fallback, but glow's output is clearer therefore glow is recommended)

Configuration

The configuration is done in the ./programs/ directory, which should be located in the same working directory as the xdg-ninja.sh script. This can be overridden with the XN_PROGRAMS_DIR environment variable.

You define a program, and then a list of files and directories which that program ruthlessly puts into your $HOME directory.

For each file/directory, you specify if it can be (re)moved.

If this is the case, you also specify instructions on how to accomplish this in Markdown.

Files in this directory can have any name, but using the name of the program is recommended.

Automatically Generating Configuration

For x86_64 Linux systems, you can download the xdgnj binary from the releases page.

Alternatively, you can build it from source using cabal or stack, use the nix flake or use the provided docker image.

To be clear, this is just a tool that will help you automatically generate the config files, you still only need your shell to run the tests

Available commands

xdgnj add # Adds a new configuration
xdgnj prev programs/FILE.json # Preview the configuration for a program
xdgnj edit programs/FILE.json # Edit the configuration for a program
xdgnj run # Mostly the same as running the shell script

Prebuilt Binaries

Important

The binaries only run on x86_64 Linux systems.

curl -fsSL -o xdgnj https://github.com/b3nj5m1n/xdg-ninja/releases/latest/download/xdgnj
chmod +x xdgnj

Building from source

You can use cabal build or stack build

Nix

nix run github:b3nj5m1n/xdg-ninja#xdgnj-bin ...

Docker

Use the provided dockerfile in ./haskell/build/.

Manually Creating Configuration

We're going to use git as an example.

By default, it puts the file .gitconfig into $HOME.

Luckily, the XDG spec is supported by git, so we can simply move the file to $XDG_CONFIG_HOME/git/config.

We can use that last sentence as our instructions. In this case, there are no newlines, so escaping this string for use in json is trivial, however, this is how you should generally approach it:

echo "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_." | jq -aRs .

Let's see what the output of this command looks like for something a little more sophisticated.

Here's an example file:

cat example.md

Currently not fixable.

_(But you can probably just delete the dir)_

Here's what catting this file into jq produces:

cat example.md | jq -aRs .

"Currently not fixable.\n\n_(But you can probably just delete the dir)_\n"

Now, we can assemble our final json file:

{
    "name": "git",
    "files": [
        {
            "path": "$HOME/.gitconfig",
            "movable": true,
            "help": "Luckily, the XDG spec is supported by git, so we can simply move the file to _$XDG_CONFIG_HOME/git/config_.\n"
        }
    ]
}

Saving this as git.json in the ./programs/ directory will result in the script picking it up and checking the file.

If you've created a configuration for a file that isn't in the official repository yet, make sure to create a pull request so that other people can benefit from it as well.

simonmichael/hledger

Robust, fast, intuitive plain text accounting tool with CLI, TUI and web interfaces.

hledger

Robust, intuitive plain text accounting

Welcome! This is a brief intro to hledger. For a more detailed version, see the home page: https://hledger.org

hledger is lightweight, cross platform, multi-currency, double-entry accounting software. It lets you track money, investments, cryptocurrencies, invoices, time, inventory and more, in a safe, future-proof plain text data format with full version control and privacy.

hledger aims to help both computer experts and regular folks gain clarity in their finances and time management. Though the UIs are basic, hledger can model any accounting situation and provide precise, clear reports. It is reliable, quick, and backed by the highly supportive Plain Text Accounting ecosystem. Using it is an excellent way to learn double entry accounting.

Compared to other PTA apps, hledger is actively maintained, with regular releases, and a strong focus on being easy to use and practical for everyday accounting.

More features:

Installs easily on unix, mac or windows
Complete, built-in documentation in multiple formats, beginner videos, tutorials etc.
Multiple UIs: command-line, terminal, web, mobile, editors/IDEs
Good at importing and exporting CSV; also outputs text/HTML/JSON/SQL
A robust, general, well-specified multi-currency accounting engine
Fast, analysing 25k transactions per second on a macbook air m1
Accurate to 255 decimal places
Supports your preferred account names, currencies, number formats
Inspired by and partly compatible with Ledger CLI; interconvertible with Beancount
Scriptable by CLI, HTTP or API, with plenty of examples
Clean Haskell codebase, continually improved since 2007, with $100 regression bounties
Free software licensed under GNU General Public License v3.0 or later.

Examples

I use hledger to:

track income and spending, sometimes with budgets
see time reports by day/week/month/project
track reimbursables, invoices and payments
predict cashflow and account balances
get accurate numbers for tax filing
research past events

Here's an example of the journal file format:

2022-01-01 opening balances as of this date
    assets🏦checking                $1000
    assets🏦savings                 $2000
    assets:cash                          $100
    liabilities:creditcard               $-50
    equity:opening/closing balances

2022-01-15 market
    expenses:food             $50
    assets:cash              $-50

2022-02-01 GOODWORKS CORP
    assets🏦checking           $1000
    income:salary                 $-1000

and some simple reports:

$ hledger bs
Balance Sheet 2022-02-15

                        || 2022-02-15 
========================++============
 Assets                 ||            
------------------------++------------
 assets🏦checking   ||      $2000 
 assets🏦savings    ||      $2000 
 assets:cash            ||        $50 
------------------------++------------
                        ||      $4050 
========================++============
 Liabilities            ||            
------------------------++------------
 liabilities:creditcard ||        $50 
------------------------++------------
                        ||        $50 
========================++============
 Net:                   ||      $4000

$ hledger is --monthly                                            
Income Statement 2022-01-01..2022-02-28                                               
                                                                                      
               ||  Jan    Feb                                                         
===============++=============                                                        
 Revenues      ||                                                                     
---------------++-------------                                                        
 income:salary ||    0  $1000                                                         
---------------++-------------                                                        
               ||    0  $1000                                                         
===============++=============                                                        
 Expenses      ||                                                                     
---------------++-------------                                                        
 expenses:food ||  $50      0                                                         
---------------++-------------                                                        
               ||  $50      0                                                         
===============++=============                                                        
 Net:          || $-50  $1000

More examples and screenshots: https://hledger.org/#how-to-get-started

hledger 1.x and 2.x

In 2026, the master branch was renamed to hledger1, and work began on hledger 2.x, now in the main branch.

Some goals for 2.x:

continue and improve 1.x's reliability
provide excellent lot tracking and capital gains calculation
explore ethical use of AI as a dev tool
more cleanup and simplification of code, docs, process, finance
more speed
more interoperability
more use of jj for version management
easier contribution

and for 1.x:

continued stability, installability
bugfix releases to fix newly discovered regressions, if any
preserve the non-AI-assisted codebase, and try to keep it that way

Funding

hledger is brought to you by Simon Michael, 140+ contributors, and the generous financial sponsors below.

After enjoying some personal or organisational success with hledger, you might want to become one of them, to help support this work. It's easy! Please see https://hledger.org/sponsor.html for details.

GitHub Haskell Monthly Trending

jgm/pandoc

Pandoc

The universal markup converter

Installing

Documentation

Contributing

License

simplex-chat/simplex-chat

SimpleX - the first messaging platform that has no user identifiers of any kind - 100% private by design!

Welcome to SimpleX Chat!

Install the app

Connect to the team

Join user groups

Follow our updates

Make a private connection

User guide (NEW)

Contribute

Help translating SimpleX Chat

Please support us with your donations

Contents

Why privacy matters

SimpleX approach to privacy and security

Complete privacy of your identity, profile, contacts and metadata

The best protection against spam and abuse

Complete ownership, control and security of your data

Users own SimpleX network

Frequently asked questions

News and updates

⚡ Quick installation of a terminal app

SimpleX Platform design

Privacy and security: technical details and limitations

For developers

Develop a chat bot

Roadmap

Disclaimers

Security contact

License

hadolint/hadolint

Hadolint - Haskell Dockerfile Linter

Table of Contents

How to use

Install

CLI

Configure

Non-Posix Shells

Ignoring Rules

Inline ignores

Global ignores

Linting Labels

Note on dealing with variables in labels

Integrations

Rules

Develop

Setup

REPL

Tests

AST

Building against custom libraries

Alternatives

PostgREST/postgrest

Sponsors

Usage

Documentation

Performance

Security

Versioning

Self-documentation

Data Integrity

Supporting development

Contributing

Thanks

koalaman/shellcheck

ShellCheck - A shell script static analysis tool

Table of Contents

How to use

On the web

From your terminal

In your editor

In your build or test suites

`cardano-node`

Using `cardano-node` and dependencies as a library

Using `git fsck`

Super Validator UIs (if LocalNet enabled via `make setup`)