{"id":13880908,"url":"https://github.com/neinteractiveliterature/intercode","last_synced_at":"2026-04-07T18:01:08.234Z","repository":{"id":3484701,"uuid":"4540352","full_name":"neinteractiveliterature/intercode","owner":"neinteractiveliterature","description":"The future of convention web applications","archived":false,"fork":false,"pushed_at":"2026-04-02T20:02:26.000Z","size":237106,"stargazers_count":26,"open_issues_count":269,"forks_count":7,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-04-03T04:44:23.349Z","etag":null,"topics":["conventions","javascript","ruby"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neinteractiveliterature.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2012-06-03T20:25:48.000Z","updated_at":"2026-04-02T17:14:42.000Z","dependencies_parsed_at":"2023-09-21T21:53:04.701Z","dependency_job_id":"e1d07000-141f-4523-a448-dda751764b37","html_url":"https://github.com/neinteractiveliterature/intercode","commit_stats":null,"previous_names":[],"tags_count":383,"template":false,"template_full_name":null,"purl":"pkg:github/neinteractiveliterature/intercode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neinteractiveliterature%2Fintercode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neinteractiveliterature%2Fintercode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neinteractiveliterature%2Fintercode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neinteractiveliterature%2Fintercode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neinteractiveliterature","download_url":"https://codeload.github.com/neinteractiveliterature/intercode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neinteractiveliterature%2Fintercode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conventions","javascript","ruby"],"created_at":"2024-08-06T08:03:38.268Z","updated_at":"2026-04-07T18:01:08.224Z","avatar_url":"https://github.com/neinteractiveliterature.png","language":"TypeScript","readme":"# Intercode\n\n[![Build Status](https://github.com/neinteractiveliterature/intercode/workflows/Docker%20Image%20CI/badge.svg)](https://github.com/neinteractiveliterature/intercode/actions?workflow=Docker+Image+CI)\n[![Automated Code Review](https://github.com/neinteractiveliterature/intercode/workflows/Pronto/badge.svg)](https://github.com/neinteractiveliterature/intercode/actions?workflow=Pronto)\n\nIntercode is a web application that:\n\n- serves as the public-facing web site for a convention\n- automates signup and payment\n- automates business processes for the convention staff\n\n[The original Intercode](https://github.com/neinteractiveliterature/intercode-classic) was written in PHP by Barry Tannenbaum for Intercon New England, and has since been used by several other conventions around the world.\n\nIntercode 2 was a ground-up rewrite of Intercode, making it more robust, more flexible, and more modern. Starting at version 3.0.0, we've used [semantic versioning](https://semver.org/) for our releases.\n\n## Overall Architecture\n\n- **Backend**: Ruby on Rails application exposing a GraphQL API and an OpenID Connect-enabled OAuth2 server\n- **Frontend**: React and Apollo-based single-page JavaScript app\n- **Database engine**: PostgreSQL\n- **Background queue system**: Amazon SQS + Shoryuken (this might change in the future)\n- **Production infrastructure**: For [New England Interactive Literature](http://interactiveliterature.org)'s installation of Intercode, we're hosting it on [Fly](https://fly.io).\n\n## Getting Started with Developing Intercode\n\n- Intercode in development mode uses `intercode.test` as its cookie domain. If you use `localhost` to visit the site, that will mysteriously fail. I'm going to try to make the site detect the wrong domain and redirect you, but for now, please just use the `intercode.test` domain name.\n- We used to support a Docker Compose-based development workflow, but this has been deprecated. Please run Rails locally using the instructions below.\n\n### Developer Setup with local Rails\n\nThis is the classic Rails development setup, and should work for Mac and Linux users. Windows users should use WSL.\n\n#### Dev tooling setup using mise\n\nIn this tutorial, we're going to set up [mise-en-place](https://mise.jdx.dev) to manage the versions of Ruby and Node.js used to run Intercode. This will be a globally-installed tool on your system, so if you don't want to do it this way, know that there are other options such as [rbenv](https://github.com/sstephenson/rbenv#readme).\n\nFirst, run this command to install mise globally:\n\n```sh\ncurl https://mise.run | sh\n```\n\nThis will download mise and then give you a command to run to activate mise in your shell. Run that command as well, then run:\n\n```sh\nmise doctor\n```\n\nHopefully, this will run with no issues. If it does find problems, follow its instructions to correct them.\n\nNow we need to set some settings in mise so that it will correctly pick up the tool versions Intercode uses. Run these commands:\n\n```sh\nmise settings add idiomatic_version_file_enable_tools ruby\nmise settings add idiomatic_version_file_enable_tools node\nmise settings ruby.compile=false\n```\n\n(The last one isn't strictly necessary but it should save a lot of time on the installation.)\n\n#### Setting up other dependencies\n\nOn Linux and WSL, you'll need to have a few packages installed before setting up Intercode. For Debian and Ubuntu, this command should do it:\n\n```sh\nsudo apt install build-essential git postgresql libmariadb-dev libvips zlib1g-dev libffi-dev libssl-dev libyaml-dev\n```\n\nOn macOS, you should have [Homebrew](https://brew.sh/) installed. Homebrew will also guide you through installing the Xcode command line tools. Once that's done, run this:\n\n```sh\nbrew install mysql-client postgresql\n```\n\nIn order to connect to your local PostgreSQL instance and set up Intercode, you'll need to have a user with enough permissions to log in and create databases. First, run this:\n\n```sh\nsudo -u postgres psql postgres\n```\n\nThis should bring you into a Postgres command prompt. You'll need to run a few commands that include your local username on your Linux or macOS machine:\n\n```sql\nCREATE ROLE [your username];\nALTER USER [your username] login;\nALTER USER [your username] createdb;\n```\n\nNow exit the Postgres command prompt using Ctrl-D, and run:\n\n```sh\npsql postgres\n```\n\nThis should let you into Postgres, this time as your local user account.\n\n#### Setting up Intercode\n\nFirst, clone this repository:\n\n```sh\ngit clone https://github.com/neinteractiveliterature/intercode.git\n```\n\ncd into the checked-out repository and have mise install Ruby and Node automatically:\n\n```sh\ncd intercode\nmise install\n```\n\nIntercode ships with a sample settings file that has credentials for external services the app uses. We'll need to make a copy of it so that we can set up those credentials as needed. For now, we'll leave all the actual credentials blank:\n\n```sh\ncp .env.development.local.sample .env.development.local\n```\n\nNow let's install the Ruby and Node.js dependencies of the app:\n\n```sh\nbundle install\ncorepack enable\nyarn install\n```\n\n#### Setting up the database\n\nIn theory, it should be possible to set up your local database using this command:\n\n```sh\nbin/rails db:create db:migrate db:seed\n```\n\nThere are a few things that can go wrong here. Let's go through some common types of errors and how you can fix them:\n\n\u003cdetails\u003e\n\n\u003csummary\u003e`PG::ConnectionBad: connection to server at \"::1\", port 5432 failed: fe_sendauth: no password supplied (PG::ConnectionBad)`\u003c/summary\u003e\n\nIf you're seeing something like this, you probably need to force Rails to connect to the database server using a UNIX socket as opposed to trying to connect via localhost TCP port 5432. To do this, we'll need to change the `DATABASE_URL` environment variables. Start by copying these lines from `.env.development` into `.env.development.local`:\n\n```text\nDEVELOPMENT_DATABASE_URL=postgresql://localhost/intercode_development\nTEST_DATABASE_URL=postgresql://localhost/intercode_test\n```\n\nThen, add the path to the UNIX socket as a `?host=` parameter at the end of both URLs. On Debian, the path to the socket is `/var/run/postgresql`, so these lines would become:\n\n```text\nDEVELOPMENT_DATABASE_URL=postgresql://localhost/intercode_development?host=/var/run/postgresql\nTEST_DATABASE_URL=postgresql://localhost/intercode_test?host=/var/run/postgresql\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003e`psql:/home/debian/intercode/db/structure.sql:4: ERROR:  unrecognized configuration parameter \"transaction_timeout\"`\u003c/summary\u003e\n\nIf you're seeing something like this, you're probably running an older version of PostgreSQL than the one Intercode supports. We tend to track new PostgreSQL releases pretty closely, so you probably\nneed the latest version available.\n\n\u003c/details\u003e\n\n#### Setting up weird web serving nonsense\n\nIntercode uses a somewhat unfortunate custom setup for local HTTP. Because some features require HTTPS, we generate a self-signed CA and certificate. In addition, Intercode expects to have different domain names for each convention it hosts, so we set up \\*.intercode.test as a private fake DNS namespace for the local copy of Intercode to use.\n\nFirst, let's generate the self-signed certificates:\n\n```sh\ngem install toys\ntoys setup_tls\n```\n\nOn macOS, the above command will prompt for your password and install the CA in your local keychain. On other OSes, you'll have to do this step manually from your browser (later in the process).\n\nNow, let's set up the private DNS namespace. The setup for this differs somewhat between different operating systems:\n\n\u003cdetails\u003e\n\u003csummary\u003emacOS\u003c/summary\u003e\n\nOn macOS, create a file called `/etc/resolver/intercode.test` with the following contents:\n\n```text\ndomain intercode.test\nnameserver 127.0.0.1\n```\n\nTo test that this is working, try running `ping randomname.intercode.test`. It should start pinging your local machine on 127.0.0.1.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eLinux\u003c/summary\u003e\n\nOn Linux, there's no built-in way to do wildcard domain resolution like there is with macOS's resolver. But, we can use dnsmasq as a DNS resolver proxy and configure it to resolve \\*.intercode.test to 127.0.0.1. First, install dnsmasq:\n\n```sh\nsudo apt install dnsmasq\n```\n\nThen create a file called `/etc/dnsmasq.d/dnsmasq-intercode.conf` with the following contents:\n\n```text\naddress=/intercode.test/127.0.0.1\n```\n\nNow we need to get dnsmasq to play nice with systemd, which at least in Debian's setup, it won't do by default. First, edit `/etc/dnsmasq.conf` and add these lines:\n\n```text\nlisten-address=127.0.0.2\nbind-interfaces\n```\n\nThis will make dnsmasq listen on 127.0.0.2, which won't conflict with systemd-resolved. We also need to get it to stop trying to listen on 127.0.0.1. To do that, edit `/etc/default/dnsmasq` and find the commented-out line that says `DNSMASQ_EXCEPT=\"lo\"`. Uncomment it:\n\n```text\nDNSMASQ_EXCEPT=\"lo\"\n```\n\nNow restart dnsmasq:\n\n```sh\nsudo systemctl restart dnsmasq\n```\n\nOnce that's done, edit `/etc/systemd/resolved.conf` and find the commented-out line that begins with `DNS=`. Change it to say:\n\n```text\nDNS=127.0.0.2\n```\n\nNow restart systemd-resolved:\n\n```sh\nsudo systemctl restart systemd-resolved.service\n```\n\nTo test that this is working, try running `ping randomname.intercode.test`. It should start pinging your local machine on 127.0.0.1.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows\u003c/summary\u003e\n\nOn Windows, there's no built-in way to do wildcard domain resolution like there is with macOS's resolver. But, we can use a DNS resolver proxy such as [Acrylic](https://mayakron.altervista.org/support/acrylic/Home.htm) and configure it to resolve \\*.intercode.test to 127.0.0.1.\n\nI have not personally tried this, but if someone does and would like to contribute instructions to this README, I would be forever grateful!\n\n\u003c3, Nat\n\n\u003c/details\u003e\n\n#### Starting Intercode for the first time\n\nYou'll need two terminals (or two terminal tabs) for this. In the first, start up the Rails backend server:\n\n```sh\nbin/rails server\n```\n\nIn the second, start up the Vite frontend server:\n\n```sh\nyarn run start\n```\n\nYou should now be able to go to \u003chttps://intercode.test:5050\u003e and see the app running!\n\nIf you don't, you probably need to import the self-signed CA to your local keychain. In Chrome and Chromium-based browsers, you'll probably get an error that allows you to go ahead and trust the CA, which you should do.\n\nIn Firefox, the browser will likely hang forever when trying to load the page. You'll have to go into Firefox's security settings and go to Certificates, and import the `dev_ca.crt` file (generated in a previous step) as a trusted CA for websites.\n\n#### Making yourself a local admin\n\nNow let's make you a local administrator. Open a third terminal and run:\n\n```sh\nbin/rails console\n```\n\nAt the Rails console prompt, use a command like this to create an admin user:\n\n```ruby\nUser.create!(email: 'your email address here', first_name: 'your first name here', last_name: 'your last name', password: 'your password', site_admin: true)\n```\n\nThis will create an account for you in your local database with the `site_admin` flag turned on. You should now be able to log into your local copy of Intercode and access all the admin functionality.\n\n## Testing production builds\n\nIf you want to test how the app runs in production, but using your local development installation, you can do so as follows:\n\n1. Build Docker images for Intercode: `docker build --target production -t local-intercode-production .`\n2. Install the `dev-proxy` npm package: `npm install -g dev-proxy`\n3. Run `dev-proxy` to start proxying HTTPS locally: `dev-proxy -p 5051:5050`\n4. Run something like the following command, changing the asset host as necessary for your setup: `docker run -it -p 5051:3000 -e DATABASE_URL=postgresql://postgres@docker.for.mac.localhost/intercode_development -e RAILS_LOG_TO_STDOUT=true -e ASSETS_HOST=//intercont.intercode.test:5050 -e RAILS_SERVE_STATIC_FILES=true local-intercode-production bin/rails`\n5. Visit \u003chttps://some-convention-domain.intercode.test:5050\u003e, probably using Firefox (it seems to deal better than Chrome with self-signed certificates these days).\n\n## Contacting us\n\nTo contact the Intercode project team, you can:\n\n- [File an issue or feature request here](https://github.com/neinteractiveliterature/intercode/issues)\n- [Email Nat Budin](mailto:natbudin@gmail.com).\n\n## Code of Conduct\n\nParticipants in the Intercode project are expected to follow the Contributor Covenant. For details, [see CODE_OF_CONDUCT.md](https://github.com/neinteractiveliterature/intercode/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nIntercode is released under the terms and conditions of the MIT license. Please see the LICENSE file for the full legalese.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneinteractiveliterature%2Fintercode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneinteractiveliterature%2Fintercode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneinteractiveliterature%2Fintercode/lists"}