Getting set up to contribute to dev-docs requires that you have both the Space-Age and dev-docs GitLab repositories cloned to your local machine. The links to both can be found below.
Since the dev-docs repository is being hosted by Space Age (which has its own deps.edn), you will need to include any dependencies that your CLJ scripts require in $HOME/.clojure/deps.edn for the user running the Space Age server. This is the current set of required dependencies:
{:deps {org.clojure/core.async {:mvn/version "1.3.618"}
org.clojure/core.match {:mvn/version "1.0.0"}
org.clojure/data.json {:mvn/version "2.0.1"}
clj-http/clj-http {:mvn/version "3.12.1"}}}Once you've made sure that your $HOME/.clojure/deps.edn file is up to date, you will need to create a self-signed TLS Certificate in order to run Space Age locally. Navigate to the root directory of `space-age` and run the following `keytool` command to generate a 2048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 365 days:
cd /path/to/space-age keytool -genkey -keyalg RSA -keysize 2048 -alias selfsigned -validity 365 -keystore resources/keystore.jks -storepass moonshot
When prompted for "your first and last name" (the Common Name), you should put "localhost" since we'll be running dev-docs on Space Age locally. You can leave all of the other prompts blank.
The `keytool` command creates a `keystore.jks` file in the `resources` directory with a password of “moonshot”. If you want the file to have a different name or password or to be located somewhere else, just change the `keytool` arguments accordingly.
If you don't change the keystore file name/location or its password, then you're all set! If you do decide to change any of these, then you'll have to update the values assigned to the `-Djavax.net.ssl.keyStore` or `-Djavax.net.ssl.keyStorePassword` attributes under the `:jvm-opts` settings in the `:run-server` alias of the `space-age` `deps.edn` file.
Besides the /opertions page, the entirety of dev-docs is publically visible. In order to view the /operations page on your Gemini client you'll need to generate another self-signed SSL certificate, this time for your Gemini client of choice.
The Java `keytool` command can be used to generate public/private keypairs, certificates, and certificate-signing requests (CSRs). It can also be used to sign requests. Before Java 9, JKS was its default keystore format. With Java 9 and later, PKCS12 is the default keystore format.
The following are the steps needed to get access to the /operations page:
1. Generate a new self-signed certificate in PKCS12 format. This can be done in a temporary directory.
keytool -genkeypair -keyalg RSA -keysize 2048 -validity 365 -alias your_alias -keystore your_keystore.pkcs12 -storepass your_password
2. Export the public key certificate from the keystore in PEM format:
keytool -exportcert -rfc -alias your_alias -keystore your_keystore.pkcs12 -storepass your_password -file your_cert.crt
Note: The `-rfc` option sets the output file format to PEM. Otherwise, it will be DER.
Alternatively, you can use openssl for the same purpose:
openssl pkcs12 -in your_keystore.pkcs12 -nokeys -out your_cert.crt
3. Export the private key from the keystore in PEM format:
openssl pkcs12 -in your_keystore.pkcs12 -nodes -nocerts -out your_key.key
4. Open your Gemini client and add your .crt and .key files to it as valid identites. The process to do so is different depending on your client. On Lagrange, you can add these files by opening the sidebar, clicking the identity tab, and clicking the import button.
5. DM your .crt and .key files to Gary Johnson on Mattermost. Once Gary adds your certificate to the dev-docs repository, you should be able to view the /operations page.
6. You can now delete your .pkcs12, .crt, and .key files from the temporary directory you created earlier.
Now that we have Space Age and our certifications properly set up, running dev-docs locally is as simple as navigating to the `space-age` directory and running the following command:
cd /path/to/space-age clojure -M:default-ssl-opts:run-server /path/to/dev-docs/document-root
Pointing your Gemini client at gemini://localhost/ should now show you dev-docs in all of its glory! You can now make changes to your heart's content and submit them via MRs to the `dev-docs` repository.
Happy hacking!