Skip to content

Commit 5fd927e

Browse files
nbudinnbudin
authored
Merge pull request #11242 from neinteractiveliterature/readme-updates
Improve developer setup docs and add root site CMS content set
2 parents e2dd9b8 + b0a3e70 commit 5fd927e

27 files changed

Lines changed: 798 additions & 77 deletions

‎README.md‎

Lines changed: 268 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -11,58 +11,283 @@ Intercode is a web application that:
1111

1212
[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.
1313

14-
Intercode 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.
14+
Intercode 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.
1515

16-
# Overall Architecture
16+
## Overall Architecture
1717

1818
- **Backend**: Ruby on Rails application exposing a GraphQL API and an OpenID Connect-enabled OAuth2 server
1919
- **Frontend**: React and Apollo-based single-page JavaScript app
2020
- **Database engine**: PostgreSQL
2121
- **Background queue system**: Amazon SQS + Shoryuken (this might change in the future)
2222
- **Production infrastructure**: For [New England Interactive Literature](http://interactiveliterature.org)'s installation of Intercode, we're hosting it on [Fly](https://fly.io).
2323

24-
# Getting Started with Developing Intercode
24+
## Getting Started with Developing Intercode
2525

2626
- 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.
2727
- We used to support a Docker Compose-based development workflow, but this has been deprecated. Please run Rails locally using the instructions below.
2828

29-
## Developer Setup with local Rails
30-
31-
This is the classic Rails development setup, and should work for Mac and Linux users.
32-
33-
1. Clone this repository: `git clone https://github.com/neinteractiveliterature/intercode.git`
34-
2. Make sure you have a working C/C++ development toolchain installed. On macOS, that's Xcode and its Command Line Tools.
35-
3. Install [rbenv](https://github.com/sstephenson/rbenv#readme)
36-
4. Install [ruby-build](https://github.com/sstephenson/ruby-build#readme)
37-
5. Edit your hosts file (typically found in `/etc/hosts` on Mac and Linux systems) and add the following line: `127.0.0.1 intercode.test`
38-
6. `cd` to the Intercode source folder, all the remaining steps should be performed in that folder.
39-
7. Copy `.env.development.local.sample` to `.env.development.local` and follow the instructions in
40-
that file to set up keys for various external services. You'll almost certainly need to set up
41-
reCAPTCHA; the others are probably best left until you really need to.
42-
8. Install all the dependencies of Intercode:
43-
44-
1. Install the Ruby version Intercode requires: `rbenv install`
45-
2. Install Bundler: `gem install bundler`
46-
3. Install PostgreSQL. With Homebrew: `brew install postgres`
47-
4. Make sure you have Node.js installed. With Homebrew: `brew install node`
48-
5. Make sure you have Yarn installed. With Homebrew: `brew install yarn`
49-
6. `bundle install`
50-
51-
9. Generate self-signed certificates to support HTTPS
52-
53-
1. `gem install toys`
54-
2. `toys setup_tls`
55-
56-
10. Set up your local database: `bin/rails db:create db:migrate`
57-
11. Install JavaScript packages: `yarn install`
58-
12. Start up the Intercode server: `bin/rails server`
59-
13. Start up the Webpack server: `yarn run start`
60-
14. You should now be able to go to <https://intercode.test:5050> and see the app running!
61-
15. Click the user icon in the upper right of the navigation bar and choose "Sign up" to sign up for
62-
an account in your local copy of Intercode.
63-
16. To make yourself a superadmin in your local copy, run `./bin/rails console`. At the Rails
64-
console prompt, type `User.first.update!(site_admin: true)`. This will set the `site_admin`
65-
flag on your account in the database, giving you superadmin powers.
29+
### Developer Setup with local Rails
30+
31+
This is the classic Rails development setup, and should work for Mac and Linux users. Windows users should use WSL.
32+
33+
#### Dev tooling setup using mise
34+
35+
In 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).
36+
37+
First, run this command to install mise globally:
38+
39+
```sh
40+
curl https://mise.run | sh
41+
```
42+
43+
This will download mise and then give you a command to run to activate mise in your shell. Run that command as well, then run:
44+
45+
```sh
46+
mise doctor
47+
```
48+
49+
Hopefully, this will run with no issues. If it does find problems, follow its instructions to correct them.
50+
51+
Now we need to set some settings in mise so that it will correctly pick up the tool versions Intercode uses. Run these commands:
52+
53+
```sh
54+
mise settings add idiomatic_version_file_enable_tools ruby
55+
mise settings add idiomatic_version_file_enable_tools node
56+
mise settings ruby.compile=false
57+
```
58+
59+
(The last one isn't strictly necessary but it should save a lot of time on the installation.)
60+
61+
#### Setting up other dependencies
62+
63+
On 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:
64+
65+
```sh
66+
sudo apt install build-essential git postgresql libmariadb-dev libvips zlib1g-dev libffi-dev libssl-dev libyaml-dev
67+
```
68+
69+
On 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:
70+
71+
```sh
72+
brew install mysql-client postgresql
73+
```
74+
75+
In 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:
76+
77+
```sh
78+
sudo -u postgres psql postgres
79+
```
80+
81+
This 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:
82+
83+
```sql
84+
CREATE ROLE [your username];
85+
ALTER USER [your username] login;
86+
ALTER USER [your username] createdb;
87+
```
88+
89+
Now exit the Postgres command prompt using Ctrl-D, and run:
90+
91+
```sh
92+
psql postgres
93+
```
94+
95+
This should let you into Postgres, this time as your local user account.
96+
97+
#### Setting up Intercode
98+
99+
First, clone this repository:
100+
101+
```sh
102+
git clone https://github.com/neinteractiveliterature/intercode.git
103+
```
104+
105+
cd into the checked-out repository and have mise install Ruby and Node automatically:
106+
107+
```sh
108+
cd intercode
109+
mise install
110+
```
111+
112+
Intercode 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:
113+
114+
```sh
115+
cp .env.development.local.sample .env.development.local
116+
```
117+
118+
Now let's install the Ruby and Node.js dependencies of the app:
119+
120+
```sh
121+
bundle install
122+
corepack enable
123+
yarn install
124+
```
125+
126+
#### Setting up the database
127+
128+
In theory, it should be possible to set up your local database using this command:
129+
130+
```sh
131+
bin/rails db:create db:migrate db:seed
132+
```
133+
134+
There are a few things that can go wrong here. Let's go through some common types of errors and how you can fix them:
135+
136+
<details>
137+
138+
<summary>`PG::ConnectionBad: connection to server at "::1", port 5432 failed: fe_sendauth: no password supplied (PG::ConnectionBad)`</summary>
139+
140+
If 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`:
141+
142+
```text
143+
DEVELOPMENT_DATABASE_URL=postgresql://localhost/intercode_development
144+
TEST_DATABASE_URL=postgresql://localhost/intercode_test
145+
```
146+
147+
Then, 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:
148+
149+
```text
150+
DEVELOPMENT_DATABASE_URL=postgresql://localhost/intercode_development?host=/var/run/postgresql
151+
TEST_DATABASE_URL=postgresql://localhost/intercode_test?host=/var/run/postgresql
152+
```
153+
154+
</details>
155+
156+
<details>
157+
158+
<summary>`psql:/home/debian/intercode/db/structure.sql:4: ERROR: unrecognized configuration parameter "transaction_timeout"`</summary>
159+
160+
If 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
161+
need the latest version available.
162+
163+
</details>
164+
165+
#### Setting up weird web serving nonsense
166+
167+
Intercode 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.
168+
169+
First, let's generate the self-signed certificates:
170+
171+
```sh
172+
gem install toys
173+
toys setup_tls
174+
```
175+
176+
On 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).
177+
178+
Now, let's set up the private DNS namespace. The setup for this differs somewhat between different operating systems:
179+
180+
<details>
181+
<summary>macOS</summary>
182+
183+
On macOS, create a file called `/etc/resolver/intercode.test` with the following contents:
184+
185+
```text
186+
domain intercode.test
187+
nameserver 127.0.0.1
188+
```
189+
190+
To test that this is working, try running `ping randomname.intercode.test`. It should start pinging your local machine on 127.0.0.1.
191+
192+
</details>
193+
194+
<details>
195+
196+
<summary>Linux</summary>
197+
198+
On 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:
199+
200+
```sh
201+
sudo apt install dnsmasq
202+
```
203+
204+
Then create a file called `/etc/dnsmasq.d/dnsmasq-intercode.conf` with the following contents:
205+
206+
```text
207+
address=/intercode.test/127.0.0.1
208+
```
209+
210+
Now 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:
211+
212+
```text
213+
listen-address=127.0.0.2
214+
bind-interfaces
215+
```
216+
217+
This 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:
218+
219+
```text
220+
DNSMASQ_EXCEPT="lo"
221+
```
222+
223+
Now restart dnsmasq:
224+
225+
```sh
226+
sudo systemctl restart dnsmasq
227+
```
228+
229+
Once that's done, edit `/etc/systemd/resolved.conf` and find the commented-out line that begins with `DNS=`. Change it to say:
230+
231+
```text
232+
DNS=127.0.0.2
233+
```
234+
235+
Now restart systemd-resolved:
236+
237+
```sh
238+
sudo systemctl restart systemd-resolved.service
239+
```
240+
241+
To test that this is working, try running `ping randomname.intercode.test`. It should start pinging your local machine on 127.0.0.1.
242+
243+
</details>
244+
245+
<details>
246+
<summary>Windows</summary>
247+
248+
On 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.
249+
250+
I have not personally tried this, but if someone does and would like to contribute instructions to this README, I would be forever grateful!
251+
252+
<3, Nat
253+
254+
</details>
255+
256+
#### Starting Intercode for the first time
257+
258+
You'll need two terminals (or two terminal tabs) for this. In the first, start up the Rails backend server:
259+
260+
```sh
261+
bin/rails server
262+
```
263+
264+
In the second, start up the Vite frontend server:
265+
266+
```sh
267+
yarn run start
268+
```
269+
270+
You should now be able to go to <https://intercode.test:5050> and see the app running!
271+
272+
If 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.
273+
274+
In 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.
275+
276+
#### Making yourself a local admin
277+
278+
Now let's make you a local administrator. Open a third terminal and run:
279+
280+
```sh
281+
bin/rails console
282+
```
283+
284+
At the Rails console prompt, use a command like this to create an admin user:
285+
286+
```ruby
287+
User.create!(email: 'your email address here', first_name: 'your first name here', last_name: 'your last name', password: 'your password', site_admin: true)
288+
```
289+
290+
This 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.
66291

67292
## Testing production builds
68293

@@ -74,17 +299,17 @@ If you want to test how the app runs in production, but using your local develop
74299
4. 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`
75300
5. Visit <https://some-convention-domain.intercode.test:5050>, probably using Firefox (it seems to deal better than Chrome with self-signed certificates these days).
76301

77-
# Contacting us
302+
## Contacting us
78303

79304
To contact the Intercode project team, you can:
80305

81306
- [File an issue or feature request here](https://github.com/neinteractiveliterature/intercode/issues)
82307
- [Email Nat Budin](mailto:natbudin@gmail.com).
83308

84-
# Code of Conduct
309+
## Code of Conduct
85310

86311
Participants 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).
87312

88-
# License
313+
## License
89314

90315
Intercode is released under the terms and conditions of the MIT license. Please see the LICENSE file for the full legalese.

‎app/models/root_site.rb‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
# rubocop:enable Layout/LineLength, Lint/RedundantCopDisableDirective
2424

2525
class RootSite < ApplicationRecord
26-
belongs_to :root_page, class_name: 'Page'
27-
belongs_to :default_layout, class_name: 'CmsLayout'
26+
belongs_to :root_page, class_name: "Page", optional: true
27+
belongs_to :default_layout, class_name: "CmsLayout", optional: true
2828

2929
def self.instance
3030
RootSite.first
@@ -62,10 +62,22 @@ def cms_graphql_queries
6262
CmsGraphqlQuery.global
6363
end
6464

65+
def notification_templates
66+
NotificationTemplate.none
67+
end
68+
69+
def forms
70+
Form.none
71+
end
72+
6573
def host
6674
Rails.application.config.action_mailer.default_url_options[:host]
6775
end
6876

77+
def name
78+
"Root site"
79+
end
80+
6981
def url
7082
Rails.application.routes.url_helpers.root_url(Rails.application.config.action_mailer.default_url_options)
7183
end

0 commit comments

Comments
 (0)