Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use <details> in installation section #556

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Use <details> in installation section #556

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6a8bc98
Update README.md
aashi-ihsaa May 29, 2023
1478b78
Use `<details>` in installation section
duesee Nov 3, 2023
82247e8
Fix typos and improve wording in README.md
duesee Nov 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 132 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

mkcert is a simple tool for making locally-trusted development certificates. It requires no configuration.

```
```sh
$ mkcert -install
Created a new local CA 💥
The local CA is now installed in the system trust store! ⚡️
Expand All @@ -23,90 +23,183 @@ The certificate is at "./example.com+5.pem" and the key at "./example.com+5-key.

<p align="center"><img width="498" alt="Chrome and Firefox screenshot" src="https://user-images.githubusercontent.com/1225294/51066373-96d4aa80-15be-11e9-91e2-f4e44a3a4458.png"></p>

Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like `example.test`, `localhost` or `127.0.0.1`), but self-signed certificates cause trust errors. Managing your own CA is the best solution, but usually involves arcane commands, specialized knowledge and manual steps.
Using certificates from real certificate authorities (CAs) for development can be dangerous or impossible (for hosts like `example.test`, `localhost`, or `127.0.0.1`), but self-signed certificates cause trust errors. Managing your own CA is the best solution, but it usually involves arcane commands, specialized knowledge, and manual steps.

mkcert automatically creates and installs a local CA in the system root store, and generates locally-trusted certificates. mkcert does not automatically configure servers to use the certificates, though, that's up to you.

## Installation

> **Warning**: the `rootCA-key.pem` file that mkcert automatically generates gives complete power to intercept secure requests from your machine. Do not share it.
> [!WARNING]
> **Do not share the `rootCA-key.pem` file!** This file gives complete power to intercept secure requests from your machine.

### macOS
<details>
<summary><b>macOS</b></summary>

On macOS, use [Homebrew](https://brew.sh/)
<details>
<summary>Homebrew</summary>

```
See [Homebrew](https://brew.sh/).

```sh
brew install mkcert
brew install nss # if you use Firefox
# If you use Firefox:
brew install nss
```
</details>

or [MacPorts](https://www.macports.org/).
<details>
<summary>MacPorts</summary>

```
See [MacPorts](https://www.macports.org).

```sh
sudo port selfupdate
sudo port install mkcert
sudo port install nss # if you use Firefox
# If you use Firefox:
sudo port install nss
```
</details>

### Linux
</details>

On Linux, first install `certutil`.
<details>
<summary><b>Linux</b></summary>

```
<details>
<summary>APT (Debian, Ubuntu, ...)</summary>
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These instructions are from the cherry-pick.


First, install `certutil`:

```sh
sudo apt install libnss3-tools
-or-
sudo yum install nss-tools
-or-
```

Then, install `mkcert`:

```sh
sudo apt install mkcert
```
</details>

<details>
<summary>pacman (Arch, ...)</summary>

First, install `certutil`:

```sh
sudo pacman -S nss
-or-
sudo zypper install mozilla-nss-tools
```

Then you can install using [Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux)
Then, install `mkcert`:

```sh
sudo pacman -Syu mkcert
```
brew install mkcert
</details>

<details>
<summary>Yum (Fedora, ...)</summary>

First, install `certutil`:

```sh
sudo yum install nss-tools
```

or build from source (requires Go 1.13+)
Then, follow the [alternative steps below](#linux-alternative).
</details>

<details>
<summary>Zypper (openSUSE, ...)</summary>

First, install `certutil`:

```sh
sudo zypper install mozilla-nss-tools
```
git clone https://github.com/FiloSottile/mkcert && cd mkcert
go build -ldflags "-X main.Version=$(git describe --tags)"

Then, follow the [alternative steps below](#linux-alternative).
</details>

#### Linux (Alternative)

<details>
<summary>Homebrew on Linux</summary>

See [Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux).

```sh
brew install mkcert
```
</details>

or use [the pre-built binaries](https://github.com/FiloSottile/mkcert/releases).
<details>
<summary>Build from source (requires Go 1.13+)</summary>

```sh
git clone https://github.com/FiloSottile/mkcert
cd mkcert
go build -ldflags "-X main.Version=$(git describe --tags)"
```
</details>

<details>
<summary>Use pre-built binaries</summary>

See [pre-built binaries](https://github.com/FiloSottile/mkcert/releases).

```sh
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
```
</details>

For Arch Linux users, [`mkcert`](https://www.archlinux.org/packages/community/x86_64/mkcert/) is available on the official Arch Linux repository.
</details>

```
sudo pacman -Syu mkcert
```
<details>
<summary><b>Windows</b></summary>

### Windows
<details>
<summary>Chocolatey</summary>

On Windows, use [Chocolatey](https://chocolatey.org)
See [Chocolatey](https://chocolatey.org).

```
```sh
choco install mkcert
```
</details>

or use Scoop
<details>
<summary>Scoop</summary>

```
See [Scoop](https://scoop.sh/).

```sh
scoop bucket add extras
scoop install mkcert
```
</details>

#### Windows (Alternative)

<details>
<summary>Build from source (requires Go 1.10+)</summary>

```sh
<not documented yet>
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new structure made it explicit that this wasn't documented. I can't provide this information, but having it here signals that it's possible (of course :-)). We could also remove it.

```
</details>

<details>
<summary>Use pre-built binaries</summary>

See [pre-built binaries](https://github.com/FiloSottile/mkcert/releases).
</details>

or build from source (requires Go 1.10+), or use [the pre-built binaries](https://github.com/FiloSottile/mkcert/releases).
If you're encountering permission problems, try running `mkcert` as an Administrator.

If you're running into permission problems try running `mkcert` as an Administrator.
</details>

## Supported root stores

Expand Down Expand Up @@ -165,7 +258,7 @@ mkcert [email protected]

### Mobile devices

For the certificates to be trusted on mobile devices, you will have to install the root CA. It's the `rootCA.pem` file in the folder printed by `mkcert -CAROOT`.
For the certificates to be trusted on mobile devices, you must install the root CA. It's the `rootCA.pem` file in the folder printed by `mkcert -CAROOT`.

On iOS, you can either use AirDrop, email the CA to yourself, or serve it from an HTTP server. After opening it, you need to [install the profile in Settings > Profile Downloaded](https://github.com/FiloSottile/mkcert/issues/233#issuecomment-690110809) and then [enable full trust in it](https://support.apple.com/en-nz/HT204477).

Expand All @@ -181,13 +274,13 @@ export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

### Changing the location of the CA files

The CA certificate and its key are stored in an application data folder in the user home. You usually don't have to worry about it, as installation is automated, but the location is printed by `mkcert -CAROOT`.
The CA certificate and its key are stored in an application data folder in the user home. You usually don't have to worry about it, as the installation is automated, but the location is printed by `mkcert -CAROOT`.

If you want to manage separate CAs, you can use the environment variable `$CAROOT` to set the folder where mkcert will place and look for the local CA files.
If you want to manage separate CAs, use the environment variable `$CAROOT` to set the folder where mkcert will place and look for the local CA files.

### Installing the CA on other systems

Installing in the trust store does not require the CA key, so you can export the CA certificate and use mkcert to install it in other machines.
Installing in the trust store does not require the CA key, so you can export the CA certificate and use mkcert to install it on other machines.

* Look for the `rootCA.pem` file in `mkcert -CAROOT`
* copy it to a different machine
Expand Down