Merge pull request #470 from jyn514/docker-instructions

Instructions and bugfixes for docker

Author: pietroalbini

Dockerfile

@@ -60,7 +60,11 @@ RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y \
     git \
     libmagic1 \
     docker.io \
-    ca-certificates
+    ca-certificates \
+    build-essential \
+    gcc \
+    pkg-config \
+    libssl-dev
 
 RUN mkdir -p /opt/docsrs/prefix
 
@@ -71,4 +75,4 @@ COPY docker-entrypoint.sh /opt/docsrs/entrypoint.sh
 
 WORKDIR /opt/docsrs
 ENTRYPOINT ["/opt/docsrs/entrypoint.sh"]
-CMD ["daemon", "--foreground"]
+CMD ["start-web-server"]

README.md

@@ -49,8 +49,9 @@ Example badges for `mio` crate:
 
 ## Development
 
-We strongly recommend using docker-compose, which will make it easier to get started
-without adding new users and packages to your host machine.
+We strongly recommend using [docker-compose](https://docs.docker.com/compose/),
+which will make it easier to get started without adding new users and packages
+to your host machine.
 
 ### Getting started
 
@@ -60,7 +61,19 @@ Make sure you have docker-compose and are able to download ~10GB data on the fir
 git clone https://github.com/rust-lang/docs.rs.git docs.rs
 cd docs.rs
 cp .env.sample .env
-docker-compose up  # This may take a half hour or more on the first run
+
+docker-compose build  # This builds the docs.rs binary
+
+# Build a sample crate to make sure it works
+# This sets up the docs.rs build environment, including installing the nightly
+# Rust toolchain. This will take a while the first time but will be cached afterwards.
+docker-compose run web build crate regex 1.3.1
+
+# This starts the web server but does not build any crates.
+# If you want to build crates, see below under `build` subcommand.
+# It should print a link to the website once it finishes initializing.
+docker-compose up
+
 ```
 
 If you need to store big files in the repository's directory it's recommended to
@@ -91,7 +104,7 @@ This is probably because you have `git.autocrlf` set to true,
 ```sh
 # This command will start web interface of docs.rs and you can access it from
 # http://localhost:3000/`
-docker-compose run -p 3000:3000 web start-web-server
+docker-compose up
 ```
 
 #### `build` subcommand
@@ -126,15 +139,24 @@ docker-compose run web database add-directory <DIRECTORY> [PREFIX]
 docker-compose run web database update-github-fields
 ```
 
-If you want to explore or edit database manually, you can connect database
-with `psql` command.
+If you want to explore or edit database manually, you can connect to the database
+with the `psql` command.
 
 ```sh
 # this will print the name of the container it starts
 docker-compose run -d db
 docker exec -it <the container name goes here> psql -U cratesfyi
 ```
 
+#### `daemon` subcommand
+
+```sh
+# Run a persistent daemon which queues builds and starts a web server.
+# Warning: This will try to queue hundreds of packages on crates.io, only start it
+# if you have enough resources!
+docker-compose run -p 3000:3000 web daemon --foreground
+```
+
 ### Contact
 
 Docs.rs is run and maintained by [Rustdoc team](https://www.rust-lang.org/governance/teams/dev-tools#rustdoc).

src/web/mod.rs

@@ -441,7 +441,11 @@ pub fn start_web_server(sock_addr: Option<&str>) {
     metrics::UPLOADED_FILES_TOTAL.inc_by(0);
 
     let cratesfyi = CratesfyiHandler::new();
-    Iron::new(cratesfyi).http(sock_addr.unwrap_or("0.0.0.0:3000")).unwrap();
+    let addr = sock_addr.unwrap_or("0.0.0.0:3000");
+    // need to assign this so it's not dropped before the function ends
+    let _server = Iron::new(cratesfyi).http(addr)
+        .unwrap_or_else(|_| panic!("Failed to bind to socket on {}", addr));
+    info!("Running docs.rs web server on http://{}", addr);
 }