Easy to read HOWTO's or anything similar?

[Johan Sunnerstig <Jo...@netgiro.com>]

Hi.

Just wondering if anyone knows of any good howto's or guides about setting
up a Tomcat server?
The reference docs are good as a reference, but less than stellar for
someone setting up their first server IMO.

Or, if such a thing does not exist, could someone just tell me how a very
basic server.xml might look?
Say I just wanna setup a server, serving nothing but static pages, what
would be the minimum config I'd need for that?

Thanks
Johan

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Easy to read HOWTO's or anything similar?

[Paul Brinkley <la...@starpower.net>]

At 11:14 AM 8/29/2002 +0200, Johan Sunnerstig wrote:

 > Just wondering if anyone knows of any good howto's or guides about setting
 > up a Tomcat server?
 > The reference docs are good as a reference, but less than stellar for
 > someone setting up their first server IMO.

I have to admit I was a bit lost when I first tried this, too.  This was
despite reading the Tomcat documentation three times, and moreover having
made a servlet before, for Apache (around 1999, I think, so it'd been a
while).  There's evidence that the documentation isn't complete (literally
a "Todo: write this section" blurb somewhere in the text; Term2 and
Term3???, etc.)

Setting up the server itself was easy.  Set two vars and run startup.
Piece o'cake.  The trouble came when trying to develop.

I come from a Java application background.  I've been writing Java code
since 1997.  I have less experience as a web programmer - I've written a
few hundred lines of Javascript, set up a few Apache servers, one or two
Java applets, and I once scribbled a servlet front-end to a shell interface
on the host computer.

My usual tactic when learning this stuff is to come up with a "hello
world", and then hack from there.  I looked at the examples folder first,
which was probably a big help, but still left me with questions like:

- How do I put a servlet in its own separate "workspace"?  (I wasn't yet
   hip on the context concept.)  Hacking, I tried copying some source from
   examples, changing it, then attempting to compile it and run it.
- How do I simplify the link to my servlet?  I had this horrid
   "localhost/myServlet/servlets/myServlet" thing.  (This required a few
   days of reading and hacking until I knew my way around conf/server.xml
   enough to fix it.  myServlet was repeated, because I apparently needed to
   specify both the context and the name of the actual servlet in the link,
   even though the doc says a context is a webapp.  That confused me quite a
   bit.)
- How do I add an existing jar to a servlet's classpath, if that jar
   doesn't want to live under WEB-INF/lib?  (I ultimately asked this here,
   and got a solid "you can't" response, so I'm satisfied.  However, I've
   seen this asked here often, so it'd make a great FAQ submission.

All the while, I was having to learn all new terminology.  Context,
deployment, container, WAR, virtual host, JSP, etc.  Fortunately, there's a
Terminology section in the intro.  Woo-hoo!  Unfortunately - well, check it
out for yourself.  :-)

To set up my development environment, I went to the app-dev guide.  Great.
But, uh, what is Ant?  I had never heard of Ant before installing Tomcat.
It took me at least a minute or two to cop to the fact that the docs were
referring to another Jakarta component.  Back to Jakarta.  OK, cool, Ant is
a make utility.  But I was still in hack mode, trying to get something
working right away, and having to DL and install yet another thing which
could go wrong wasn't going to help me.  Ant's great, I'm sure (I have yet
to get it working), but small bites, please.

One of the underlying problems I slowly realized in hindsight was that the
docs explained several ways to do various things, in an effort to be
complete.  That's good.  However, it was hard for me to tell which was the
"simplest" way, or the "default" way, to do something.  For me, learning is
like exploration.  You start in familiar territory, and then take
reasonably small sojourns into the unknown, going further each time, until
the new area is understood.  I felt like I had to map the Louisiana
Territory without a bathroom break.

Online help is an exercise in self-torture.  The Jakarta FAQ-o-matic link
flat out doesn't work (server not found).  I went to JGuru, which gets more
frustrating the more I go to it.  First of all, JGuru's FAQ isn't an FAQ;
it's a forum.  The "FAQ" has heaps of questions there with no answers, or
unhelpful answers.  (java.sun.com's forums have this same problem.)  The
questions aren't organized by topic.  To me, an FAQ should really have its
questions arranged by topic, rather than merely searchable.  Many users
will be coming to an FAQ without much prior experience, and thus have
little idea of what search keywords to use, but they will at least have a
general idea of what they need help on.  And the latest cheek is that now
JGuru seems to want to charge for this frustration.  Usenet has slim
pickings as far as Tomcat goes.  This mailing list is pretty much it, and
by far the most helpful, but after going through all the earlier options, I
was pretty run down.

Next was to find an archive for this list.  For some reason, I ended up in
a hard-to-use archive that only apparently archived up to last March.  I
can't seem to find that link now.  The archive links in my Tomcat doc go to
much more friendly interfaces.  (Maybe I got that link from JGuru.)  In any
case, more frustration, but that was my bad, I think.

I have yet to read the Servlet Specification, and I should.  Past
experience with specs, however, indicates that one shouldn't read them when
looking for a tutorial.  Now that I see them (why are there no readily
available links for browsing this as online HTML?  What are we,
Visigoths??), they seem kinda easy to read.  Should the Tomcat docs goad
the reader a bit harder to read them first?

Apologies for the long screed.  I'm trying to establish that I came to
these impressions after a lot of reading, which BTW aren't limited to what
I've mentioned above.  I'm also trying to describe my learning experience
in detail sufficient to aid any effort to improve the docs.  Speaking of
which, I'd like to see a few low-cost changes to the introduction.html
page, which I think would be immensely helpful:

- Expand the Terminology section.  (There's one term and two placeholders.)
- Fix or remove the FAQ-o-matic link.
- Put the JGuru link near the bottom, and one of this list's archive links
   near the top.  People will have much less trouble in my considered
   opinion if they search this list first.  JGuru should now be a last
   resort.

Finally, does anyone here think there would be merit in a tutorial targeted
at Java coders with fairly little web experience, such as myself?


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>