Skip to content

Commit fc981da

Browse files
kentcdoddskentcdodds
committed
add decision doc about source maps (closes #178) and add docs about secrets management
1 parent 73090e7 commit fc981da

File tree

3 files changed

+126
-0
lines changed

3 files changed

+126
-0
lines changed

‎docs/README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,22 @@ or
1414

1515
This stack is still under active development. Documentation will rapidly improve
1616
in the coming weeks. Stay tuned!
17+
18+
# Top Pages
19+
20+
- [Getting Started](./getting-started.md) - Instructions for how to get started
21+
with the Epic Stack.
22+
- [Features](./features.md) - List of features the Epic Stack provides out of
23+
the box.
24+
- [Deployment](./deployment.md) - If you skip the deployment step when starting
25+
your app, these are the manual steps you can follow to get things up and
26+
running.
27+
- [Decisions](./decisions/README.md) - The reasoning behind various decisions
28+
made for the Epic Stack. A good historical record.
29+
- [Guiding Principles](./guiding-principles.md) - The guiding principles behind
30+
the Epic Stack.
31+
- [Examples](./examples.md) - Examples of the Epic Stack with various tools.
32+
Most new feature requests people have for the Epic Stack start as examples
33+
before being integrated into the framework.
34+
- [Managing Updates](./managing-updates.md) - How to manage updates to the Epic
35+
Stack for both the generated stack code as well as npm dependencies.

‎docs/decisions/016-source-maps.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Source Maps
2+
3+
Date: 2023-06-14
4+
5+
Status: accepted
6+
7+
## Context
8+
9+
If you're unfamiliar with source maps, check out
10+
[What are source maps?](https://web.dev/source-maps/) on web.dev.
11+
12+
For anyone familiar with source maps, it's pretty obvious that you do want these
13+
in production for debugging purposes (read
14+
[Should I Use Source Maps in Production? ](https://css-tricks.com/should-i-use-source-maps-in-production/)).
15+
However, when you enable source maps with Remix, you get a warning that looks
16+
like this:
17+
18+
```
19+
> remix build --sourcemap
20+
21+
Building Remix app in production mode...
22+
23+
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
24+
You have enabled source maps in production. This will make your server-side code visible to the public and is highly discouraged! If you insist, please ensure you are using environment variables for secrets and not hard-coding them into your source!
25+
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
26+
```
27+
28+
It's pretty well understood that source maps allow your code to be visible to
29+
the public and yet it's still pretty well understood that's fine because
30+
client-side apps send the code anyway and that can typically be reverse
31+
engineered (especially with the help of modern AI tools as well).
32+
33+
The reason it's a special concern for some frameworks like Remix today is
34+
because the source maps for the client-side code include some of the server-side
35+
code as well. This is because Remix and other frameworks like it have the
36+
ability for you to write your server code in the same file as your browser code.
37+
38+
The ability for the public to view your server-side code understandably raises
39+
some concerns for folks. This is especially dangerous if you have secrets
40+
hard-coded into your server-side code. Additionally, if you're exercising
41+
"security through obscurity" then you may be vulnerable to attacks if your
42+
server-side code is visible.
43+
44+
On the flip side, you really shouldn't be hard-coding secrets into your
45+
server-side code anyway. You should be using environment variables for that.
46+
Additionally, if you're relying on "security through obscurity" then you're
47+
probably not as secure as you think you are.
48+
49+
Also, source maps are necessary for error monitoring with tools like Sentry.
50+
Without source maps, you'll only see the minified code in your error monitoring
51+
tools. This makes it much harder to debug errors in production. And if you're
52+
debugging your application in production you'll also be limited to minified code
53+
as well.
54+
55+
It may be possible to generate the source maps and make them available to
56+
Sentry, but then prevent them from being sent to the client. More research is
57+
needed to determine whether this is possible.
58+
59+
## Decision
60+
61+
We've decided to enable source maps in production by default. This will allow
62+
for better error monitoring and debugging in production. It will also allow for
63+
easier debugging of server-side code in production.
64+
65+
## Consequences
66+
67+
Developers using the Epic Stack will see an warning message during the build and
68+
if they don't practice good secret "hygiene" they may be vulnerable to attacks.
69+
So we'll add documentation explaining how to properly use environment variables
70+
for secrets and not hard-code them into your source code.

‎docs/sectets.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Secrets
2+
3+
Managing secrets in the Epic Stack is done using environment variables and the
4+
`fly secrets` command.
5+
6+
> **Warning**: It is very important that you do NOT hard code any secrets in the
7+
> source code. Even if your app source is not public, there are a lot of reasons
8+
> this is dangerous and in the epic stack we default to creating source maps
9+
> which will reveal your hard coded secrets to the public. Read more about this
10+
> in [the source map decision document](./decisions/016-source-maps.md).
11+
12+
## Local development
13+
14+
When you need to create a new secret, it's best to add a line to your
15+
`.env.example` file so folks know that secret is necessary. The value you put in
16+
here should be not real because this file is committed to the repository.
17+
18+
To keep everything in line with the [guiding principle](./guiding-principles.md)
19+
of "Offline Development," you should also strive make it so whatever service
20+
you're interacting with can be mocked out using MSW in the `test/mocks`
21+
directory.
22+
23+
You can also put the real value of the secret in `.env` which is `.gitignore`d
24+
so you can interact with the real service if you need to during development.
25+
26+
## Production secrets
27+
28+
To publish a secret to your production and staging applications, you can use the
29+
`fly secrets set` command. For example, if you were integrating with the `tito`
30+
API, to set the `TITO_API_SECRET` secret, you would run the following command:
31+
32+
```sh
33+
fly secrets set TITO_API_SECRET=some_secret_value
34+
fly secrets set TITO_API_SECRET=some_secret_value --app [YOUR_STAGING_APP_NAME]
35+
```
36+
37+
This will redeploy your app with that environment variable set.

0 commit comments

Comments
 (0)